Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / cxl50.arc / CXL.DOC next >

Wrap

Text File | 1989-07-11 | 254KB | 8,759 lines

C X L The C Programmer's Extended Function Library Version 5.0 March 27, 1989 by Mike Smedley Copyright (c) 1987-1989 All Rights Reserved Reference Manual Table of Contents Introduction................................1 General Information....................1 Features of the CXL Library............1 Registration Information...............3 How to Contact the Author..............5 Disclaimer.............................5 Trademarks.............................5 Using CXL Functions....................6 Global Variables............................7 _kbinfo................................7 _mouse.................................7 _vinfo.................................7 _winfo.................................8 Library Functions..........................10 attrib................................10 beep..................................10 biosver...............................10 box_..................................11 capsoff...............................11 capson................................12 cclrscrn..............................12 clearkeys.............................12 clockcal..............................13 clreol_...............................13 clrscrn...............................13 clrwin................................13 cvaltype..............................14 cvtcf.................................14 cvtci.................................15 cvtfc.................................15 cvtic.................................16 cxlver................................16 delay_................................17 disktoscrn............................17 disktowin.............................18 EMS Functions.........................18 emsalloc..............................19 emsdealloc............................20 emsexist..............................20 emsframe..............................21 emsfree...............................21 emsmap................................21 emsread...............................22 emstotal..............................22 emsver................................23 emswrite..............................23 expmem................................23 extmem................................24 fcrypt................................24 fill_.................................25 gameport..............................25 getchf................................26 i getcursz..............................26 getns.................................27 getxch................................27 gotoxy_...............................28 hidecur...............................28 inputsf...............................28 kbclear...............................29 kbmhit................................29 kbput.................................30 kbputs................................30 kbstat................................31 lcrlf.................................31 lgcursor..............................32 lprintc...............................32 lprintf...............................32 lprintns..............................33 lprints...............................33 lprintsb..............................34 lprintsu..............................34 machid................................34 mapattr...............................35 mathchip..............................35 mode..................................36 msbclear..............................36 msbpress..............................36 msbreles..............................37 mscondoff.............................38 mscursor..............................38 msgotoxy..............................39 mshbounds.............................39 mshidecur.............................40 msinit................................40 msmotion..............................41 msshowcur.............................41 msspeed...............................41 msstatus..............................42 mssupport.............................42 msvbounds.............................43 numflop...............................43 numoff................................44 numon.................................44 numpar................................44 numser................................45 printc................................45 prints................................45 putchat...............................46 randfile..............................46 readchat..............................47 readcur...............................47 revattr...............................48 revsattr..............................48 scancode..............................48 scrndump..............................49 scrntodisk............................49 ii setattr...............................50 setcursz..............................50 setkbloop.............................50 setlines..............................51 setonkey..............................51 showcur...............................52 smcursor..............................52 sound_................................53 spc...................................53 srestore..............................53 ssave.................................54 strblank..............................54 strbmatch.............................55 strchg................................55 strchksum.............................56 strcode...............................56 strdel................................57 strichg...............................57 strichksum............................58 stridel...............................58 striinc...............................59 strinc................................59 strins................................60 striocc...............................61 strisocc..............................61 strisrep..............................62 strleft...............................62 strljust..............................63 strltrim..............................63 strmatch..............................64 strmid................................64 strocc................................65 strright..............................65 strrjust..............................66 strrol................................66 strror................................67 strsetsz..............................67 strshl................................68 strshr................................69 strsocc...............................69 strsrep...............................70 strtrim...............................70 struplow..............................71 sysdate...............................71 systime...............................72 tabstop...............................72 timer.................................73 touplow...............................73 videoinit.............................74 vidtype...............................74 wactiv................................75 waitkey...............................75 waitkeyt..............................76 wborder...............................76 iii wbox..................................77 wcclear...............................77 wcenters..............................78 wchgattr..............................78 wchkbox...............................79 wchkcol...............................79 wchkcoord.............................80 wchkrow...............................80 wclear................................81 wclose................................81 wcloseall.............................81 wclreol...............................82 wclreos...............................82 wcopy.................................82 wdelline..............................83 wdump.................................84 wdupc.................................84 wdups.................................85 werrmsg...............................85 wfill.................................86 wfillch...............................86 wfindrec..............................87 wgetc.................................87 wgetchf...............................87 wgetns................................88 wgets.................................89 wgotoxy...............................89 whandle...............................90 Context-Sensitive Help Functions......90 whelpcat..............................92 whelpclr..............................92 whelpdef..............................93 whelpop...............................93 whelpopc..............................94 whelpush..............................94 whelpushc.............................94 whide.................................95 whline................................95 windowat..............................96 windump...............................96 Multi-Field Input Functions...........97 winpbeg...............................99 winpdef..............................100 winpfba..............................100 winpfcurr............................101 winpffind............................102 winpread.............................102 winputsf.............................103 winsline.............................103 wintodisk............................104 wisactiv.............................104 Bar Menu Functions...................105 wmenubeg.............................106 wmenubegc............................107 iv wmenuend.............................108 wmenuget.............................109 wmenuiba.............................109 wmenuicurr...........................110 wmenuifind...........................111 wmenuitem............................111 wmenuitxt............................112 wmenumcurr...........................113 wmessage.............................113 wmove................................114 wopen................................114 wperror..............................115 wpgotoxy.............................116 wpickfile............................116 wpickstr.............................117 wprintc..............................118 wprintf..............................119 wprints..............................119 wprintsf.............................120 wputc................................121 wputns...............................121 wputs................................122 wputsw...............................122 wreadcur.............................123 wrestore.............................123 wrjusts..............................124 wsave................................124 wscanf...............................125 wscroll..............................125 wscrollbox...........................126 wselstr..............................126 wsetesc..............................127 wshadoff.............................127 wshadow..............................128 wsize................................128 wtabwidth............................129 wtextattr............................129 wtitle...............................130 wunhide..............................130 wvline...............................131 wwprints.............................132 Appendix A - Text Attribute Identifiers...133 Appendix B - Keycode Table................134 Appendix C - Window Output Escape Codes...136 Appendix D - Format Control Characters....137 Appendix E - Input Field Editing Keys.....140 v Introduction General Information. The CXL library is intended to be a supplement to your C compiler's standard run-time library. It contains over 230 multi-purpose functions which provide a variety of capabilities. It is available for several popular C compilers including Microsoft C, QuickC, Turbo C, Power C, and Zortech C/C++. These routines were written in 100% highly-optimized C code ensuring maximum program speed, minimum program size, easy modification, and increased portability. This release is an evaluation release containing everything you need to write C programs using the small memory model. The libraries for the other memory models are supplied when you register. Features of the CXL Library. o Powerful windowing system. Allows as many open windows as memory permits. Windows can be stacked, tiled, shadowed, moved, resized, and changed in many other ways. There is a whole assortment of various input and output functions to interract with windows. o Multi-field formatted data entry. You can create data entry forms that consist of one or more input fields. You have full control over user input and can tie validation functions into each input field. Features alpha and numeric justification, capitalization conversion, formatting characters, and a large assortment of editing keys. o Moving bar menus. You can easily create pop-up, pull-down, and Lotus-style menus, as well as any other custom menu that you can define. Features full mouse support, nonselectable items, global hot keys, and more. o Scrollable pick menus. Allow you to pick one item from a list of items. Features full mouse support and scroll bars. There is also a dedicated file picker that uses this feature to let you pick from a list of files, very similar to the way that the Turbo C and QuickC environments' file pickers work. o Context-sensitive help system. Help files are indexed for speed. Help categories can be cross-referenced. Help can be applied at the global, window, menu item, and input field levels. o Several video output methods. These include direct screen writing, direct screen writing with CGA snow reduction, video BIOS writing, and DESQview video buffer writing. These will allow you to be video compatible with virtually any video adapter or multitasking environment. 1 o EGA 43 and VGA 50-line modes. CXL provides functions to directly change to and from these modes. CXL's video functions are also compatible with nonstandard modes such as 132x80 and 120x43. o Extensive mouse support. Mouse movements can be translated into keypresses, and several CXL functions have a "point-and-shoot" type of mouse support that utilizes a free-moving mouse cursor. There are also several functions for directly manipulating Microsoft-compatible mice. o Keyboard management routines. Allows you to tie keystrokes to functions, stuff and clear the keyboard buffer, set and read the keyboard shift/toggle keys, and specify a function to be called while waiting for a keypress. o Advanced string manipulation. There are a host of string manipulation functions that perform searching, replacing, formatting, conversion, rotating, shifting, pattern matching, encryption, and other string operations. o Several other functions for expanded memory (EMS) usage, file encryption, date and time formatting, equipment detection, printing, sound, and more. 2 Registration Information. CXL is distributed as User-Supported software. You are free to copy and distribute this software freely, however, if you find it of use to you, you are encouraged to register your copy. Registering your copy of the software helps the author continue to provide professional-quality software at very reasonable prices. The Basic Registration is $35.00 and includes the full library source code, one library disk of your choice, batch files to build and update the libraries, royalty-free use of library functions, unlimited technical support, and low-cost upgrades. Library disks are available for Microsoft C/QuickC, Turbo C, Zortech C/C++, and Power C. Since you will have the source code, you will be able to use it to build any of the libraries for the supported compilers. However, if you don't want to hassle with building libraries, pre-compiled library disks are available for an additional $5.00 each (one library disk is included in the Basic Registration). All materials are shipped on 5.25-inch floppy diskettes, however, there is a 3.5-inch floppy diskette service available for an additional $5.00. This is a once-per-order charge that covers as many 3.5-inch floppy disks as are needed to ship your order. Non-U.S. orders need to include $5.00 extra to cover additional shipping and handling charges. Checks and money orders must be drawn on a U.S. bank. Please send all payments payable in U.S. Dollars. Print the registration form, REGISTER.DOC, or include on a piece of paper your name, address, phone number, and brand of compiler, and send it along with your payment to: Mike Smedley P.O. Box 33603 San Antonio, TX 78265-3603 If by chance, you don't have the REGISTER.DOC file, a copy of the registration form is included on the next page. 3 CXL REGISTRATION FORM NAME: ______________________________________________________ COMPANY: ______________________________________________________ ADDRESS: ______________________________________________________ ______________________________________________________ CITY: ______________________________________________________ STATE: ________________________ ZIP CODE: _________________ PHONE: ______________________________________________________ E-MAIL ADDRESS: _______________________________________________ WHERE DID YOU RECEIVE CXL? ____________________________________ ________________________________________________________________ COMMENTS: _____________________________________________________ ________________________________________________________________ ________________________________________________________________ Basic Registration @ $35.00 $__________ (Circle ONE library disk) Microsoft Turbo Zortech Power Additional Library Disks @ $5.00 each __________ (Circle each ADDITIONAL library disk) Microsoft Turbo Zortech Power 3.5-Inch Floppy Disk Service @ $5.00 __________ Non-US Shipping @ $5.00 __________ (Payments must be in US Dollars, US bank) 5.0 TOTAL: $__________ Remit to: Mike Smedley P.O. Box 33603 San Antonio, TX 78265-3603 4 How to Contact the Author. Primary: Official CXL Support BBS - (512) 590-0460 1200/2400 Alternate: CompuServe - 71331,2244 GEnie - M.SMEDLEY Telstar BBS - (512) 822-8882 1200/2400 U.S. Mail - see address above Disclaimer. The author claims no responsibility for any damages caused by the use or misuse of this product. This product is distributed "as is" with no warranty expressed or implied. The author will not be responsible for any losses incurred, either directly or indirectly, by the use of this product. The author reserves the right to make modifications at any time. Prices are subject to change without notice. Trademarks. CompuServe is a registered trademark of CompuServe Incorporated. DESQview is a trademark of Quarterdeck Office Systems. Epson is a registered trademark of Seiko Epson Corporation. GEnie is a trademark of GE Information Services. IBM is a registered trademark of International Business Machines. LIM and EMS are trademarks of Lotus, Intel, and Microsoft Corporations. Lotus is a registered trademark of Lotus Development Corporation. Microsoft is a registered trademark of Microsoft Corporation. Power C is a trademark of Mix Software, Inc. Turbo C is a registered trademark of Borland International. Zortech is a trademark of Zortech Inc. 5 Using CXL Functions. For every CXL function you use, there should be a corresponding CXL header file #included at the top of your program. The CXL header files should follow your standard compiler header files. For example: #include <dos.h> #include <stdio.h> #include "cxldef.h" #include "cxlwin.h" The basic command line compiler/linker commands to build your file containing CXL functions are as follows: Microsoft C: cl myfile.c cxlmss.lib Quick C: qcl myfile.c cxlmss.lib Power C: pc -c -d__POWERC__ myfile.c pcl myfile.mix ;cxlpcm.mix Turbo C: tcc myfile.c cxltcs.lib Zortech C/C++: ztc myfile.c cxlzts.lib /* for C programs */ ztc myfile.cpp cxlzts.lib // for C++ programs 6 Global Variables NAME _kbinfo DESCRIPTION A record which holds keyboard information. The individual structure elements are: kbuf - pointer to head record in key buffer. onkey - pointer to head record in onkey list. kbloop - pointer to function to call while waiting for a keypress. This variable should be set with the setkbloop() function. inmenu - inmenu flag used internally by the menuing and picking functions to help control mouse support. SYNOPSIS #include "cxlkey.h" struct _kbinfo_t _kbinfo; ------------------------------------------------------------------------ NAME _mouse DESCRIPTION This variable is set by the msinit() and/or mssupport() function. It contains MS_NONE by default. If msinit() detects a mouse, it will set _mouse to MS_KEYS. Also see the function descriptions of msinit() and mssupport(). SYNOPSIS #include "cxlmou.h" int _mouse; ------------------------------------------------------------------------ NAME _vinfo DESCRIPTION The video information record. The videoinit() function is responsible for setting most of the elements in this record. If you don't call videoinit(), they will default to CGA settings. If you modify any of these, you must modify them AFTER the call to videoinit(). The one exception is _vinfo.dvcheck which, if used, must be set BEFORE the call to videoinit(). The individual structure elements are: videoseg - video buffer segment address. Default is 0xb800. adapter - video adapter type. Default is V_CGA. numrows - number of displayed rows. Default is 25. numcols - number of displayed columns. Default is 80. cheight - character height in pixels. Default is 8. 7 cwidth - character width in pixels. Default is 8. mono - is it a monochrome video adapter? Default is 0. mapattr - map color attribs to monochrome attribs? By default, if a monochrome video adapter is detected by videoinit(), then all color attributes will be mapped to monochrome equivalents. To disable this automatic mapping, set _vinfo.mapattr=0;. Default is 1. cgasnow - is CGA snow present? To turn snow reduction on, set _vinfo.cgasnow=1;. Default is 0. retminch - minimum number of characters required to wait for vertical retrace. If you write a string whose length is less than this value, CXL will use BIOS instead of waiting for vertical retrace. This is only used when _vinfo.cgasnow==1. Default is 10. usebios - use BIOS for video writes? To use BIOS for video writes, set _vinfo.usebios=1;. dvcheck - check for DESQview? To disable videoinit() from checking for DESQview, set _vinfo.dvcheck=0; before calling videoinit(). Default is 1. dvexist - is DESQview present? Default is 0. SYNOPSIS #include "cxlvid.h" struct _vinfo_t _vinfo; ------------------------------------------------------------------------ NAME _winfo DESCRIPTION The window information record. The individual structure elements are: active - pointer to active window's record. hidden - pointer to head hidden window's record. menu - pointer to head menu's record. cmenu - pointer to current menu's record. help - current help category number. handle - last handle given to a window. Every time wopen() creates a new window, it increments this value. errno - error number from last windowing function. Most windowing functions set this variable before returning. The werrmsg() function returns a literal representation of this value. total - total number of open windows. mlevel - system variable used by menu functions. ilevel - system variable used by menu functions. esc - check for [Esc] in input funcions? You should use the wsetesc() function to set this value. Default is 1 (yes). tabwidth - window TTY output tab width. You can use wtabwidth() to set this value. Default is 8. fillch - character to fill windows with. You should use wfillch() to set this value. Default is ' '. 8 SYNOPSIS #include "cxlwin.h" struct _winfo_t _winfo; 9 Library Functions NAME attrib DESCRIPTION Creates a text attribute. It is usually much easier to create a text attribute using the attribute identifiers listed in Appendix A, but this provides an alternate method. SYNOPSIS #include "cxlvid.h" int attrib(int fore,int back,int bright,int blink); INPUTS fore - foreground color code (0-7) back - background color code (0-7) bright - intensity (0-1) blink - blinking (0-1) RETURN VALUE The new attribute code. ALSO SEE setattr wtextattr EXAMPLE prints(10,5,attrib(6,0,1,1),"Hello, world"); ------------------------------------------------------------------------ NAME beep DESCRIPTION Sounds a beep in the speaker. SYNOPSIS #include "cxldef.h" void beep(void); ALSO SEE sound_ ------------------------------------------------------------------------ NAME biosver DESCRIPTION Returns the ROM BIOS version date. SYNOPSIS 10 #include "cxldef.h" char *biosver(void); RETURN VALUE The address of the static string containing the ROM BIOS version date. ALSO SEE machid ------------------------------------------------------------------------ NAME box_ DESCRIPTION "Draws" a text box on the screen. SYNOPSIS #include "cxlvid.h" void box_(int srow,int scol,int erow,int ecol,int btype,int attr); INPUTS srow - start row of box scol - start column of box erow - end row of box ecol - end column of box btype - box type. Can be one of the following: 0 - single line 1 - double line 2 - single horz, double vert line 3 - double horz, single vert line 4 - thick line 5 - no border (uses spaces for box chars) attr - text attribute for border characters ALSO SEE fill_ EXAMPLE box_(10,10,20,40,2,YELLOW|_BLACK); ------------------------------------------------------------------------ NAME capsoff DESCRIPTION Toggles the CapsLock key off. SYNOPSIS #include "cxlkey.h" void capsoff(void); 11 ALSO SEE capson kbstat numoff numon ------------------------------------------------------------------------ NAME capson DESCRIPTION Toggles the CapsLock key on. SYNOPSIS #include "cxlkey.h" void capson(void); ALSO SEE capsoff kbstat numoff numon ------------------------------------------------------------------------ NAME cclrscrn DESCRIPTION Clears the screen using given text attribute and homes the cursor. SYNOPSIS #include "cxlvid.h" void cclrscrn(int attr); INPUTS attr - text attribute to use to clear the screen with ALSO SEE clreol_ clrscrn clrwin EXAMPLE cclrscrn(BLACK|_BLACK); ------------------------------------------------------------------------ NAME clearkeys DESCRIPTION Clears the keyboard buffer. SYNOPSIS #include <conio.h> #include "cxlkey.h" void clearkeys(void); ALSO SEE kbclear waitkey 12 ------------------------------------------------------------------------ NAME clockcal DESCRIPTION Determines if a clock-calendar board is installed. This usually will only work with the clock-calendar boards in XT-style machines. SYNOPSIS #include "cxldef.h" int clockcal(void); RETURN VALUE Nonzero if a clock-calendar board is present. ------------------------------------------------------------------------ NAME clreol_ DESCRIPTION Clears to the end of line using the text attribute under the cursor. SYNOPSIS #include "cxlvid.h" void clreol_(void); ALSO SEE cclrscrn clrscrn clrwin ------------------------------------------------------------------------ NAME clrscrn DESCRIPTION Clears the screen using the text attribute under the cursor, and homes the cursor. SYNOPSIS #include "cxlvid.h" void clrscrn(void); ALSO SEE cclrscrn clreol_ clrwin ------------------------------------------------------------------------ NAME clrwin DESCRIPTION Clears a window of the screen using the text attribute under the 13 cursor. SYNOPSIS #include "cxlvid.h" void clrwin(int srow,int scol,int erow,int ecol); INPUTS srow - start row of window scol - start column of window erow - end row of window ecol - end column of window ALSO SEE cclrscrn clreol_ clrscrn ------------------------------------------------------------------------ NAME cvaltype DESCRIPTION Checks given character against a given CXL character type code, and determines if that character is valid for that type. This function is used internally by several CXL functions. SYNOPSIS #include "cxlstr.h" int cvaltype(int ch,int ctype); INPUTS ch - character to test ctype - character type code to compare with. See section on CXL format strings for a list of valid character type codes. See Appendix D for a list of character type codes which can be used. RETURN VALUE -1 - invalid ctype was given 0 - character is not valid for given ctype 1 - character is valid for given ctype EXAMPLE printf("'A' is %sa valid character of type '#'\n",cvaltype('A','#')? "":"not "); printf("'7' is %sa valid character of type '#'\n",cvaltype('7','#')? "":"not "); ------------------------------------------------------------------------ NAME cvtcf DESCRIPTION Converts a CXL field string to a floating point number. 14 SYNOPSIS #include "cxlstr.h" double cvtcf(char *field,int wholesize,int fracsize); INPUTS field - address of CXL field string wholesize - number of whole digits fracsize - number of fractional digits RETURN VALUE A double precision floating point number. ALSO SEE cvtci cvtfc cvtic EXAMPLE double pi; pi=cvtcf("314159",1,5); printf("pi = %f\n",pi); ------------------------------------------------------------------------ NAME cvtci DESCRIPTION Converts a CXL field string to an integer. SYNOPSIS #include "cxlstr.h" int cvtci(char *field); INPUTS field - address of CXL field string RETURN VALUE An integer number. ALSO SEE cvtcf cvtfc cvtic EXAMPLE int i; i=cvtci("32767"); printf("i = %d\n",i); ------------------------------------------------------------------------ NAME cvtfc DESCRIPTION Converts a floating point number to a CXL field string. 15 SYNOPSIS #include "cxlstr.h" void cvtfc(char *field,double value,int wholesize,int fracsize); INPUTS field - address of buffer to receive field string value - floating point number to convert wholesize - number of whole digits fracsize - number of fractional digits ALSO SEE cvtcf cvtci cvtic EXAMPLE char field[8]; cvtfc(field,3.14159,2,4); printf("field = '%s'\n",field); ------------------------------------------------------------------------ NAME cvtic DESCRIPTION Converts an integer to a CXL field string. SYNOPSIS #include "cxlstr.h" void cvtic(char *field,int value,int size); INPUTS field - address of buffer to receive CXL field string value - integer value to convert size - field size ALSO SEE cvtcf cvtci cvtfc EXAMPLE char field[8]; cvtic(field,27,5); printf("field = '%s'\n",field); ------------------------------------------------------------------------ NAME cxlver DESCRIPTION Returns the CXL version number of the current CXL library in use. SYNOPSIS #include "cxldef.h" char *cxlver(void); 16 RETURN VALUE The address of the static string containing the CXL version number. ------------------------------------------------------------------------ NAME delay_ DESCRIPTION Delays program execution for a specified duration. SYNOPSIS #include "cxldef.h" void delay_(unsigned duration); INPUTS duration - duration of delay (0-65535) ie. 182 = 10 seconds ALSO SEE timer waitkeyt EXAMPLE delay_(36); /* pause for 2 seconds */ ------------------------------------------------------------------------ NAME disktoscrn DESCRIPTION Copies a previously saved screen disk file to the screen. SYNOPSIS #include "cxlvid.h" int disktoscrn(char *fname); INPUTS fname - address of the string containing file name to read from. RETURN VALUE Nonzero if an error occurred. ALSO SEE disktowin scrntodisk wintodisk EXAMPLE char fname[]="SCRN.DAT"; if(disktoscrn(fname)) { printf("Error reading file: %s\n",fname); exit(1); } ------------------------------------------------------------------------ 17 NAME disktowin DESCRIPTION Copies a previously saved window disk file to the screen. SYNOPSIS #include "cxlvid.h" int disktowin(char *fname); INPUTS fname - address of the string containing file name of file to read from. RETURN VALUE Nonzero if an error occurred. ALSO SEE disktoscrn scrntodisk wintodisk EXAMPLE char fname[]="WIND.DAT"; if(disktowin(fname)) { printf("Error reading file: %s\n",fname); exit(1); } ------------------------------------------------------------------------ EMS Functions CXL contains several functions for simple management of expanded memory. All of CXL's EMS functions are prefixed with 'ems'. For those not familiar with expanded memory, I will briefly explain it. The 8088 microprocessor is only able to address 1 Megabyte of memory. When applications started needing more memory, Lotus, Intel, and Microsoft developed the Expanded Memory Specification. This specification allows access to more than 1 Megabyte of memory by mapping 16K 'windows' of memory on an expanded memory board in and out of an unused area of DOS memory. The Expanded Memory Manager (EMM) is a software driver that controls the mapping. Physical pages are 16K blocks of memory which are located in an unused area of DOS memory. There are typically 4 physical pages comprising a 64K contiguous area of mappable DOS memory. The EMS page frame base address points to the beginning of the first physical page. Logical pages are 16K blocks of memory on the expanded memory board. There can be as many logical pages as the expanded memory board has, up to 8 Megabytes. Every program that uses expanded memory must do the following: 1. determine if the EMM device driver is loaded 18 2. determine if there are enough free pages for its application 3. allocate pages of expanded memory 4. find out what the EMS page frame base address is 5. map logical pages onto physical pages 6. deallocate pages when finished with them Here's an example of using CXL's EMS functions to perform these procedures: int handle1,handle2; char buf[14]; if(!emsexist()) { /* Check for the EMM driver. */ printf("EMM not loaded\n"); exit(1); } handle1=emsalloc(2); /* Request 2 pages of EMS */ /* memory. */ handle2=emsalloc(2); /* Request 2 more pages. */ if(handle1==-1 || handle2==-1) { /* Test for allocation error. */ printf("EMS allocation error\n"); exit(1); } emsmap(handle1,0,0); /* Map logical page 0 of handle */ /* 1 to physical page 0. */ emswrite("Hello, world",0,13); /* Write a string at offset 0, */ /* automatically determines what*/ /* the page frame address is. */ emsmap(handle2,0,0); /* Map logical page 0 of handle */ /* 2 to physical page 0. */ emswrite("How are you?",0,13); /* Write a string at offset 0. */ emsmap(handle1,0,0); /* Map logical page 0 of handle */ /* 1 to physical page 0. */ emsread(buf,0,13); /* Read 13 bytes from offset 0 */ /* into buffer. */ printf("buf = %s\n",buf); /* Display buffer contents. */ emsmap(handle2,0,0); /* Map logical page 0 of handle */ /* 2 to physical page 0. */ emsread(buf,0,13); /* Read 13 bytes from offset 0 */ /* into buffer. */ printf("buf = %s\n",buf); /* Display buffer contents. */ emsdealloc(handle2); /* Deallocate pages belonging */ /* to handle 2. */ emsdealloc(handle1); /* Deallocate pages belonging */ /* to handle 1. */ ------------------------------------------------------------------------ NAME emsalloc DESCRIPTION Allocates pages of EMS memory. SYNOPSIS 19 #include "cxlems.h" int emsalloc(int numpages); INPUTS numpages - the number of pages (16K blocks) of memory requested. For example, to allocate 512K of EMS memory, you would request 512/16, or 32 pages. RETURN VALUE The EMS handle assigned to the allocated block of memory, or -1 if an error occurred. ALSO SEE emsdealloc emsexist emsfree ------------------------------------------------------------------------ NAME emsdealloc DESCRIPTION Deallocates previously allocated pages of EMS memory. SYNOPSIS #include "cxlems.h" int emsdealloc(int handle); INPUTS handle - the EMS handle of the allocated EMS memory to deallocate RETURN VALUE Nonzero if an error occurred. ALSO SEE emsalloc emsexist ------------------------------------------------------------------------ NAME emsexist DESCRIPTION Determines if the EMS device driver is loaded. SYNOPSIS #include "cxlems.h" int emsexist(void); RETURN VALUE Nonzero if an EMS driver is loaded and functioning properly. ALSO SEE emsfree emstotal expmem 20 ------------------------------------------------------------------------ NAME emsframe DESCRIPTION Returns the EMS page frame base segment address. SYNOPSIS #include "cxlems.h" unsigned emsframe(void); RETURN VALUE The EMS page frame base segment address, or zero if an error occurred. ALSO SEE emsalloc emsexist emsmap EXAMPLE char far *p; p=MK_FP(emsframe(),0); printf("EMS memory starts at %Fp\n",p); ------------------------------------------------------------------------ NAME emsfree DESCRIPTION Returns the number of free EMS pages (16K blocks). SYNOPSIS #include "cxlems.h" unsigned emsfree(void); RETURN VALUE The number of free EMS pages. ALSO SEE emsalloc emsdealloc emstotal ------------------------------------------------------------------------ NAME emsmap DESCRIPTION Maps a logical page of allocated EMS memory onto a physical page address. SYNOPSIS #include "cxlems.h" int emsmap(int handle,int lpage,int ppage); 21 INPUTS handle - the EMS handle previosly assigned lpage - the logical EMS page to map (0 - ?) ppage - the physical DOS page to map to (0 - 3) RETURN VALUE Nonzero if an error occurred. ALSO SEE emsalloc emsdealloc emsframe ------------------------------------------------------------------------ NAME emsread DESCRIPTION Reads bytes from one or more pages of allocated EMS memory. The emsmap() function must be called prior to this function to make this memory accessible. The source segment used will be the current EMS page frame segment address and the destination segment will be your program's data segment. SYNOPSIS #include "cxlems.h" int emsread(char *dest,unsigned emsofs,unsigned numbytes); INPUTS dest - address of buffer to receive bytes read from EMS emsofs - offset from the EMS page frame base segment address to read the bytes from. numbytes - the number of bytes to read RETURN VALUE Nonzero if an error occurred. ALSO SEE emsalloc emsdealloc emsmap emswrite ------------------------------------------------------------------------ NAME emstotal DESCRIPTION Returns the total number of EMS memory pages (16K blocks) on the system. SYNOPSIS #include "cxlems.h" unsigned emstotal(void); RETURN VALUE The total number of EMS memory pages on the system. 22 ALSO SEE emsalloc emsdealloc emsexist emsfree expmem ------------------------------------------------------------------------ NAME emsver DESCRIPTION Returns the version of the EMS driver in use. SYNOPSIS #include "cxlems.h" char *emsver(void); RETURN VALUE The address of the static string containing the EMS version number, or NULL if an error occurred. ALSO SEE emsexist ------------------------------------------------------------------------ NAME emswrite DESCRIPTION Writes bytes to one or more pages of EMS memory. The emsmap() function must have been called prior to calling this function so that the EMS memory will be available. The source segment will be your program's data segment and the destination segment will be the current EMS page frame segment address. SYNOPSIS #include "cxlems.h" int emswrite(char *src,unsigned emsofs,unsigned numbytes); INPUTS src - address of buffer that contains the bytes to be written emsofs - offset from EMS page frame base segment address to write bytes to numbytes - number of bytes to write RETURN VALUE Nonzero if an error occurred. ALSO SEE emsexist emsframe emsmap emsread ------------------------------------------------------------------------ NAME expmem 23 DESCRIPTION Determines the amount, if any, of expanded memory on the system. An EMS driver does not have to be loaded to call this function. SYNOPSIS #include "cxldef.h" unsigned expmem(void); RETURN VALUE The amount of expanded memory in kilobytes. ALSO SEE emsexist extmem ------------------------------------------------------------------------ NAME extmem DESCRIPTION Determines the amount of extended memory on an AT-class machine. SYNOPSIS #include "cxldef.h" unsigned extmem(void); RETURN VALUE The amount of extended memory in kilobytes. ALSO SEE expmem ------------------------------------------------------------------------ NAME fcrypt DESCRIPTION Encrypts or decrypts a text or binary file using a modified XOR encryption method. The same encryption key string must be used when decrypting the file as when encrypting it. SYNOPSIS #include "cxldef.h" int fcrypt(char *file,char *key); INPUTS file - address of filename string of file to encrypt or decrypt. key - address of encryption key string. The string can contain any ASCII characters (01 - FF). The longer the string is, the better the encryption. Do not lose the key, or you won't see your data again! RETURN VALUE 24 Nonzero if an error occurred. ALSO SEE strcode EXAMPLE fcrypt("CXL.DOC","This is my encryption key string"); ------------------------------------------------------------------------ NAME fill_ DESCRIPTION Fills in a region of the screen with a specified character and attribute. SYNOPSIS #include "cxlvid.h" void fill_(int srow,int scol,int erow,int ecol,int ch,int attr); INPUTS srow - start row scol - start column erow - end row ecol - end column ch - character to fill with attr - attribute of character ALSO SEE attrib box_ EXAMPLE fill_(5,15,16,42,'X',LRED|_MAGENTA); ------------------------------------------------------------------------ NAME gameport DESCRIPTION Determines if a game port is installed. SYNOPSIS #include "cxldef.h" int gameport(void); RETURN VALUE Nonzero if a game port is installed. ALSO SEE mathchip numflop numpar numser ------------------------------------------------------------------------ 25 NAME getchf DESCRIPTION Gets a character from the keyboard from a list of valid characters. Provides Escape checking. SYNOPSIS #include "cxlkey.h" int getchf(char *valid,int defchar); INPUTS valid - address of string containing list of valid characters defchar - default selection in case [Enter] is pressed, or zero if you don't want to have a default selection RETURN VALUE The character pressed, or zero if the [Esc] key was pressed. ALSO SEE getxch waitkey EXAMPLE int ch; printf("Are you sure? "); ch=getchf("YyNn",'Y'); if(!ch) printf("[Esc] was pressed\n"); ------------------------------------------------------------------------ NAME getcursz DESCRIPTION Returns the start and stop scan lines of cursor. SYNOPSIS #include "cxlvid.h" void getcursz(int *sline,int *eline); INPUTS sline - address of integer to receive start scan line eline - address of integer to receive stop scan line ALSO SEE setcursz EXAMPLE int sline,eline; getcursz(&sline,&eline); printf("Cursor start & stop scan lines: %d, %d\n",sline,eline); ------------------------------------------------------------------------ 26 NAME getns DESCRIPTION Inputs a string of a specified maximum length from the keyboard. Provides Escape checking. SYNOPSIS #include "cxlkey.h" int getns(char *str,int maxchars); INPUTS str - address of buffer to receive input string maxchars - maximum length of the input string RETURN VALUE Nonzero if the [Esc] key was pressed during user input. ALSO SEE inputsf EXAMPLE char name[11]; printf("Enter your name: "); if(getns(name,10)) printf("\n[Esc] was pressed\n"); else printf("\nYour name is: %s\n",name); ------------------------------------------------------------------------ NAME getxch DESCRIPTION Gets a key (ASCII code/scan code) from the keyboard. All CXL functions that interract with the keyboard call this function for input. SYNOPSIS #include "cxlkey.h" unsigned getxch(void); RETURN VALUE The keycode of the pressed key. The keycode contains the scan code of the keypress in the upper byte, and the ASCII character in the lower byte. A list of keycodes is in Appendix B. ALSO SEE getchf EXAMPLE unsigned int keycode; printf("Press a key: "); 27 keycode=getxch(); printf("%c\nkeycode = %#x, scancode = %d, ASCII code = %d\n" ,keycode,keycode,keycode>>8,keycode&0x00ff); ------------------------------------------------------------------------ NAME gotoxy_ DESCRIPTION Sets cursor coordinates on the screen. SYNOPSIS #include "cxlvid.h" void gotoxy_(int row,int col); INPUTS row - cursor row (Y coordinate) col - cursor column (X coordinate) ALSO SEE readcur ------------------------------------------------------------------------ NAME hidecur DESCRIPTION Hides the cursor. Retains the cursor shape so that when showcur() is called, the original cursor shape will be restored. SYNOPSIS #include "cxlvid.h" void hidecur(void); ALSO SEE lgcursor setcursz showcur smcursor ------------------------------------------------------------------------ NAME inputsf DESCRIPTION Inputs a formatted string from the keyboard. This function provides an extremely powerful method of accept single-line input from the user. You can limit input characters to certain characters of a type, such as numbers, insert strings in between typed in characters, create custom prompts, disable [Enter] until the field is filled, and more. Provides Escape checking. SYNOPSIS #include "cxlkey.h" 28 int inputsf(char *str,char *fmt); INPUTS str - address of the buffer receive input string fmt - address of the format string. See Appendix D for valid format string characters. RETURN VALUE 0 - no error 1 - [Esc] key was pressed 2 - invalid format string ALSO SEE getns EXAMPLE char buf[21]; if(inputsf(buf,"'Enter your name: '!M!AAAAAAAAAAAAAAAAAAAA")==1) printf("\n[Esc] key was pressed\n"); else printf("\nYour name is: %s\n",buf); ------------------------------------------------------------------------ NAME kbclear DESCRIPTION Clears CXL's internal keyboard buffer. SYNOPSIS #include "cxlkey.h" void kbclear(void); ALSO SEE clearkeys kbmhit kbput kbputs ------------------------------------------------------------------------ NAME kbmhit DESCRIPTION Determines if a key has been pressed and is waiting to be got. Also checks for mouse button presses. Replaces the kbhit() function. SYNOPSIS #include "cxlkey.h" int kbmhit(void); RETURN VALUE Nonzero if a key is waiting to be got. ALSO SEE 29 kbclear ------------------------------------------------------------------------ NAME kbput DESCRIPTION Places a keystroke into CXL's internal keyboard buffer. This will only affect CXL's keyboard input functions. This function is useful for making keyboard scripts for demos, etc., or forcing user keyboard input. SYNOPSIS #include "cxlkey.h" int kbput(unsigned xch); INPUTS xch - keycode of keypress to place in buffer. The scan code will be in the high byte and the ASCII code will be in the low byte. See Appendix B for a list of keycodes which you can use. RETURN VALUE Nonzero if memory allocation error. ALSO SEE kbclear kbputs EXAMPLE kbput(0x011b); /* puts an [Esc] keypress into CXL's buffer */ ------------------------------------------------------------------------ NAME kbputs DESCRIPTION Places a string of characters into CXL's internal keyboard buffer. This will only affect CXL's keyboard input functions. This function is useful for making keyboard scripts for demos, etc., and forcing user keyboard input. SYNOPSIS #include "cxlkey.h" int kbputs(char *str); INPUTS str - address of string of characters to stuff into buffer RETURN VALUE Nonzero if memory allocation error. ALSO SEE kbclear kbput 30 EXAMPLE char buf[21]; kbputs("Mike"); printf("Enter your name: "); getns(buf,20); ------------------------------------------------------------------------ NAME kbstat DESCRIPTION Returns the status of the keyboard control keys. SYNOPSIS #include "cxlkey.h" unsigned kbstat(void); RETURN VALUE Status word of the keyboard flag. You can determine which key(s) are being pressed/toggled by masking the status word (using the bitwise '&' operator) with one of the following: RSHIFT - right shift pressed LSHIFT - left shift pressed CTRL - <Ctrl> pressed ALT - <Alt> pressed SCRLOCK - <Scroll Lock> toggled NUMLOCK - <Num Lock> toggled CAPSLOCK - <Caps Lock> toggled INS - <Ins> toggled ALSO SEE capsoff capson numoff numon EXAMPLE printf("NumLock is %s\n",(kbstat()&NUMLOCK)?"on":"off"); ------------------------------------------------------------------------ NAME lcrlf DESCRIPTION Prints a carriage return and line feed on the printer (PRN). SYNOPSIS #include "cxlprn.h" void lcrlf(void); ALSO SEE lprintc lprintf lprints ------------------------------------------------------------------------ 31 NAME lgcursor DESCRIPTION Makes the cursor large. SYNOPSIS #include "cxlvid.h" void lgcursor(void); ALSO SEE hidecur setcursz showcur smcursor ------------------------------------------------------------------------ NAME lprintc DESCRIPTION Prints a character on the printer (PRN). SYNOPSIS #include "cxlprn.h" void lprintc(int ch); INPUTS ch - the character to print ALSO SEE lcrlf lprintf EXAMPLE lprintc(12); /* sends a form feed to the printer */ ------------------------------------------------------------------------ NAME lprintf DESCRIPTION Sends formatted output to the printer (PRN). Works similar to the standard C printf() function. SYNOPSIS #include "cxlprn.h" void lprintf(const char *format,...); INPUTS format - format string. Refer to the section on printf() in your compiler's run-time library reference. ... - any additional arguments ALSO SEE lcrlf lprintc lprintns lprints 32 EXAMPLE char s[]="Hello"; int i=5; char c='Z'; lprintf("s = %s, i = %d, c = %c\n\f",s,i,c); ------------------------------------------------------------------------ NAME lprintns DESCRIPTION Prints a string to a fixed width on the printer (PRN). SYNOPSIS #include "cxlprn.h" void lprintns(char *str,int width); INPUTS str - the address of the string to print width - width to print string, either by padding or truncating. ALSO SEE lcrlf lprintf lprints lprintsu EXAMPLE char string[]="Hello, world"; lprintns(string,5); lprintf(".\n"); lprintns(string,20); lprintf(".\n"); ------------------------------------------------------------------------ NAME lprints DESCRIPTION Prints a string on the printer (PRN). SYNOPSIS #include "cxlprn.h" void lprints(char *str); INPUTS str - the address of the string to print ALSO SEE lcrlf lprintf lprintns lprintsu EXAMPLE lprints("Hello, world\n"); ------------------------------------------------------------------------ 33 NAME lprintsb DESCRIPTION Prints a bold-faced string on the printer (PRN). SYNOPSIS #include "cxlprn.h" void lprintsb(char *str,int reps); INPUTS str - address of the string to print reps - number of strike repetitions (the more, the darker the print) ALSO SEE lcrlf lprintf lprintns lprints lprintsu ------------------------------------------------------------------------ NAME lprintsu DESCRIPTION Prints an underlined string on the printer (PRN). SYNOPSIS #include "cxlprn.h" void lprintsu(char *str); INPUTS str - address of the string to print ALSO SEE lcrlf lprintf lprintns lprints lprintsb ------------------------------------------------------------------------ NAME machid DESCRIPTION Returns the value of the machine ROM ID byte. SYNOPSIS #include "cxldef.h" int machid(void); RETURN VALUE The value of the machine ROM ID byte. Will usually be one of the following values. Any other value is unknown. IBMPC - IBM PC IBMPCXT - IBM PC/XT IBMPCJR - IBM PCjr IBMPCAT - IBM PC/AT 34 IBMPCXT2 - IBM PC/XT-2 IBMCONV - IBM PC Convertible SPERRYPC - Sperry PC ALSO SEE biosver ------------------------------------------------------------------------ NAME mapattr DESCRIPTION Translates a color text attribute into its approximate monochrome equivalent. All of CXL's video functions automatically call this, so you would only need to call this for your own functions. SYNOPSIS #include "cxlvid.h" int mapattr(int attr); INPUTS attr - the color text attribute to translate RETURN VALUE The monochrome equivalent of the color text attribute. ALSO SEE revsattr EXAMPLE int attr=LCYAN|_BLUE; prints(0,0,attr,"In living color!"); _vinfo.mapattr=1; /* force monochrome attributes */ prints(1,0,mapattr(attr),"In dull monochrome...."); ------------------------------------------------------------------------ NAME mathchip DESCRIPTION Determines if a math coprocessor is installed. SYNOPSIS #include "cxldef.h" int mathchip(void); RETURN VALUE Nonzero if a math coprocessor is installed. ALSO SEE gameport numflop numpar numser 35 EXAMPLE printf("You do %shave a math coprocessor\n",mathchip()?"":"not "); ------------------------------------------------------------------------ NAME mode DESCRIPTION Sets the video mode. SYNOPSIS #include "cxlvid.h" void mode(int mode_code); INPUTS mode_code - video mode code ALSO SEE setlines vidtype ------------------------------------------------------------------------ NAME msbclear DESCRIPTION Clears the mouse driver's "button presses" and "button releases" counters (removes them from the queue). SYNOPSIS #include "cxlmou.h" void msbclear(void); ALSO SEE kbmhit msbpress msbreles msinit msstatus ------------------------------------------------------------------------ NAME msbpress DESCRIPTION Returns information about the specific button presses of mouse. SYNOPSIS #include "cxlmou.h" void msbpress(int button,int *bstat,int *bcount,int *row,int *col); INPUTS button - button to check: 0 - left button 1 - right button 2 - middle button (if applicable) 36 bstat - address of integer to receive button status word. Possible button status values are: 0 - no buttons pressed 1 - left button pressed 2 - right button pressed 4 - middle button pressed (if applicable) 3 - left & right buttons pressed 5 - left & middle buttons pressed (if applicable) 6 - middle & right buttons pressed (if applicable) 7 - all 3 buttons pressed (if applicable) bcount - address of integer to receive number of times pressed since last call row - address of integer to receive row at time of button press col - address of integer to receive column at time of button press ALSO SEE msbclear msbreles msinit msstatus EXAMPLE int bstat,bcount,row,col; msbpress(0,&bstat,&bcount,&row,&col); ------------------------------------------------------------------------ NAME msbreles DESCRIPTION Returns informmation about specific button releases of mouse. SYNOPSIS #include "cxlmou.h" void msbreles(int button,int *bstat,int *bcount,int *row,int *col); INPUTS button - button to check: 0 - left button 1 - right button 2 - middle button (if applicable) bstat - address of integer to receive button status word. Possible button status values are: 0 - no buttons pressed 1 - left button pressed 2 - right button pressed 4 - middle button pressed (if applicable) 3 - left & right buttons pressed 5 - left & middle buttons pressed (if applicable) 6 - middle & right buttons pressed (if applicable) 7 - all 3 buttons pressed (if applicable) bcount - address of integer to receive number of times released since last call row - address of integer to receive row at time of button release col - address of integer to receive column at time of button 37 release ALSO SEE msbclear msbpress msinit msstatus EXAMPLE int bstat,bcount,row,col; msbreles(0,&bstat,&bcount,&row,&col); ------------------------------------------------------------------------ NAME mscondoff DESCRIPTION Conditionally hides the mouse cursor depending on whether or not the mouse cursor falls within the input screen coordinates. SYNOPSIS #include "cxlmou.h" void mscondoff(int srow,int scol,int erow,int ecol); INPUTS srow - start row scol - start column erow - end row ecol - end column ALSO SEE mshidecur msinit msshowcur ------------------------------------------------------------------------ NAME mscursor DESCRIPTION Sets the mouse text cursor type. The mouse cursor can be a hardware or softare cursor. The hardware cursor is the same as the normal cursor you see when you are at the DOS prompt. Because the mouse's hardware cursor is the same as the normal cursor, they can interfere with each other, making this method impractical to use in most cases. The software mouse cursor is a text box that can reveal the underlying character. This is the cursor most used by programs including other CXL mouse support functions. SYNOPSIS #include "cxlmou.h" void mscursor(unsigned curtype,unsigned smask,unsigned cmask); INPUTS curtype - cursor type. 0=software, 1=hardware smask - screen mask (software cursor) or start scan line (hardware cursor). If using a software cursor, the screen mask 38 determines which of the characters attributes are preserved. It is ANDed with the screen character and attribute. The bit format for both smask and cmask are: Bit Content --- ------- 0-7 - ASCII character code 8-10 - foreground color 11 - 0=intensity off, 1=intensity on 12-14 - background color 15 - 0=no blink, 1=blink cmask - cursor mask (software cursor) or stop scan line (hardware cursor). If using a software cursor, the cursor mask is used to determine which of the characteristics are changed by the cursor. The cmask is XORed with the result of (smask AND character-attribute). The bit values for cmask are the same as those for smask. ALSO SEE msinit msshowcur EXAMPLE mscursor(1,1,7); /* makes a full-block hardware cursor */ msshowcur(); ------------------------------------------------------------------------ NAME msgotoxy DESCRIPTION Sets the mouse cursor coordinates. SYNOPSIS #include "cxlmou.h" void msgotoxy(int row,int col); INPUTS row - row (Y coordinate) col - column (X coordinate) ALSO SEE msinit msstatus EXAMPLE msgotoxy(13,45); /* sets mouse cursor to row 13, column 45 */ ------------------------------------------------------------------------ NAME mshbounds DESCRIPTION Sets the mouse's upper and lower horizontal bounds. 39 SYNOPSIS #include "cxlmou.h" void mshbounds(int leftcol,int rightcol); INPUTS leftcol - left column boundary rightcol - right column boundary ALSO SEE msinit msvbounds EXAMPLE mshbounds(5,45); /* restricts mouse cursor movement */ /* between columns 5 & 45 */ ------------------------------------------------------------------------ NAME mshidecur DESCRIPTION Hides the mouse cursor. SYNOPSIS #include "cxlmou.h" void mshidecur(void); ALSO SEE msinit msshowcur ------------------------------------------------------------------------ NAME msinit DESCRIPTION Determines if a mouse is present. If so, initializes mouse and sets the global variable _mouse to a MS_KEYS which causes mouse movements to be translated to the keyboard arrow keys. SYNOPSIS #include "cxlmou.h" int msinit(void); RETURN VALUE Nonzero if mouse is present. ALSO SEE mssupport EXAMPLE if(msinit()) printf("Mouse initialized\n"); else 40 printf("Mouse does not exist\n"); ------------------------------------------------------------------------ NAME msmotion DESCRIPTION Gets information about the movement of the mouse. SYNOPSIS #include "cxlmou.h" void msmotion(int *rowcount,int *colcount); INPUTS rowcount - address of integer to receive number of rows moved colcount - address of integer to receive number of columns moved ALSO SEE msinit msstatus EXAMPLE int rowcount,colcount; msmotion(&rowcount,&colcount); ------------------------------------------------------------------------ NAME msshowcur DESCRIPTION Reveals the hidden mouse cursor. SYNOPSIS #include "cxlmou.h" void msshowcur(void); ALSO SEE mscursor mshidecur msinit ------------------------------------------------------------------------ NAME msspeed DESCRIPTION Adjusts the mouse's speed by changing its sensitivity. SYNOPSIS #include "cxlmou.h" void msspeed(int xratio,int yratio); INPUTS xratio - horizontal speed (higher numbers are slower) 41 yratio - vertical speed (higher numbers are slower) ALSO SEE msinit ------------------------------------------------------------------------ NAME msstatus DESCRIPTION Returns the status of the mouse. SYNOPSIS #include "cxlmou.h" void msstatus(int *bstat,int *row,int *col); INPUTS bstat - address of integer to receive button status word. Possible button status values are: 0 - no buttons pressed 1 - left button pressed 2 - right button pressed 4 - middle button pressed (if applicable) 3 - left & right buttons pressed 5 - left & middle buttons pressed (if applicable) 6 - middle & right buttons pressed (if applicable) 7 - all 3 buttons pressed (if applicable) row - address of integer to receive current row coordinate col - address of integer to receive current column coordinate ALSO SEE msinit EXAMPLE int bstat,row,col; msstatus(&bstat,&row,&col); printf("The mouse cursor is at row %d, column %d\n",row,col); ------------------------------------------------------------------------ NAME mssupport DESCRIPTION Selects the type of mouse support to be used by CXL functions which support them. If no mouse exists, the call to this function is ignored. This function should be called after msinit(). SYNOPSIS #include "cxlmou.h" void mssupport(int type); INPUTS 42 type - type of mouse support. Can be one of the following: MS_NONE - no mouse support MS_KEYS - mouse movements are translated into keystrokes. This is the default set by msinit() if it finds a mouse driver present. MS_CURS - point-and-shoot mouse cursor where supported MS_FULL - full mouse support. If a CXL function supports a point-and-shoot mouse cursor, then that will be used, otherwise mouse movements will be translated into keystrokes. ALSO SEE msinit EXAMPLE mssupport(MS_FULL); ------------------------------------------------------------------------ NAME msvbounds DESCRIPTION Sets the mouse's left and right vertical bounds. SYNOPSIS #include "cxlmou.h" void msvbounds(int toprow,int botrow); INPUTS toprow - top row boundary botrow - bottom row boundary ALSO SEE mshbounds msinit EXAMPLE msvbounds(3,20); /* restricts mouse cursor movement */ /* between rows 3 and 20 */ ------------------------------------------------------------------------ NAME numflop DESCRIPTION Returns the number of floppy disk drives installed. SYNOPSIS #include "cxldef.h" int numflop(void); RETURN VALUE The number of floppy disk drives installed 43 ALSO SEE gameport mathchip numpar numser EXAMPLE printf("You have %d floppy drives installed\n",numflop()); ------------------------------------------------------------------------ NAME numoff DESCRIPTION Toggles the NumLock key off. SYNOPSIS #include "cxlkey.h" void numoff(void); ALSO SEE capsoff kbstat numon ------------------------------------------------------------------------ NAME numon DESCRIPTION Toggles the NumLock key on. SYNOPSIS #include "cxlkey.h" void numon(void); ALSO SEE capson kbstat numoff ------------------------------------------------------------------------ NAME numpar DESCRIPTION Returns the number of parallel ports. SYNOPSIS #include "cxldef.h" int numpar(void); RETURN VALUE The number of parallel ports installed. ALSO SEE gameport mathchip numflop numser 44 EXAMPLE printf("You have %d parallel ports\n",numpar()); ------------------------------------------------------------------------ NAME numser DESCRIPTION Returns the number of serial ports installed. SYNOPSIS #include "cxldef.h" int numser(void); RETURN VALUE The number of serial ports installed. ALSO SEE gameport mathchip numflop numpar EXAMPLE printf("You have %d serial ports\n",numser()); ------------------------------------------------------------------------ NAME printc DESCRIPTION Displays a character to the screen at a specified location, using a specified attribute. Does not recognize control characters. Does not affect cursor position. SYNOPSIS #include "cxlvid.h" void printc(int row,int col,int attr,int ch); INPUTS row - row to display character at col - column to display character at attr - text attribute for character ch - character to print ALSO SEE attrib prints EXAMPLE printc(12,40,BLINK|LRED|_BLACK,'!'); ------------------------------------------------------------------------ NAME prints 45 DESCRIPTION Displays a string on the screen at a specified location, using a specified attribute. Does not affect cursor position. SYNOPSIS #include "cxlvid.h" void prints(int row,int col,int attr,char *str); INPUTS row - row to display string at col - column to display string at attr - text attribute for characters displayed str - address of string to display ALSO SEE attrib printc EXAMPLE prints(24,15,YELLOW|_BROWN,"Hello, world"); ------------------------------------------------------------------------ NAME putchat DESCRIPTION Puts a character and its attribute on the screen at current cursor position using video BIOS calls. SYNOPSIS #include "cxlvid.h" void putchat(int ch,int attr); INPUTS ch - character to display attr - attribute to display character in ALSO SEE readchat ------------------------------------------------------------------------ NAME randfile DESCRIPTION Creates a random file name. SYNOPSIS #include "cxldef.h" char *randfile(void); RETURN VALUE Address of the static string containing the random file name. 46 EXAMPLE printf("A random file name is: %s\n",randfile()); ------------------------------------------------------------------------ NAME readchat DESCRIPTION Reads the character and attribute under the cursor using video BIOS calls. SYNOPSIS #include "cxlvid.h" unsigned readchat(void); RETURN VALUE Unsigned integer containing the character in the low byte and attribute in the high byte. ALSO SEE putchat revattr setattr EXAMPLE unsigned int chat; chat=readchat(); printf("character value = %d, attribute value = %d\n",chat&0x00ff ,chat>>8); ------------------------------------------------------------------------ NAME readcur DESCRIPTION Reads the current cursor location. SYNOPSIS #include "cxlvid.h" void readcur(int *row,int *col); INPUTS row - address of integer to receive cursor row col - address of integer to receive cursor column ALSO SEE gotoxy_ EXAMPLE int row,col; readcur(&row,&col); printf("The cursor is at row %d, column %d\n",row,col); ------------------------------------------------------------------------ 47 NAME revattr DESCRIPTION Reverses the attribute of the character under the current cursor position, and continues for the specified number of characters. Uses video BIOS calls. SYNOPSIS #include "cxlvid.h" void revattr(int count); INPUTS count - the number of characters to reverse the attribute of ALSO SEE readchat revsattr setattr EXAMPLE prints(0,0,LCYAN|_BLUE,"Hello, world"); gotoxy_(0,0); revattr(5); ------------------------------------------------------------------------ NAME revsattr DESCRIPTION Returns the inverse of the given text attribute. SYNOPSIS #include "cxlvid.h" int revsattr(int attr); INPUTS attr - text attribute RETURN VALUE The inverted text attribute. ALSO SEE mapattr revattr EXAMPLE int attr=LMAGENTA|_RED; prints(0,0,attr,"Normal"); prints(1,0,revsattr(attr),"Reverse"); ------------------------------------------------------------------------ NAME scancode 48 DESCRIPTION Returns the common scan code of the specified character. SYNOPSIS #include "cxlkey.h" int scancode(int ch); INPUTS ch - an ASCII character RETURN VALUE The common scan code of the specified character. The characters '0' thru '9', '*', '-', '+', and '.' will return their scan code from their regular keys, not their numeric keypad keys. ------------------------------------------------------------------------ NAME scrndump DESCRIPTION Dumps the current screen to the printer (PRN). SYNOPSIS #include "cxlprn.h" void scrndump(void); ALSO SEE scrntodisk ssave videoinit ------------------------------------------------------------------------ NAME scrntodisk DESCRIPTION Copies the current screen to a disk file. SYNOPSIS #include "cxlvid.h" int scrntodisk(char *fname); INPUTS fname - address of the string containing the filename of the file to write to RETURN VALUE Nonzero if an error occurred. ALSO SEE disktoscrn scrndump ssave wintodisk ------------------------------------------------------------------------ 49 NAME setattr DESCRIPTION Sets the attribute of the character under the current cursor location, and continues for the specified number of characters. Uses video BIOS calls. SYNOPSIS #include "cxlvid.h" void setattr(int attr,int count); INPUTS attr - attribute to set character count - the number of characters to set the attribute of ALSO SEE attrib readchat revattr EXAMPLE prints(0,0,LCYAN|_BLUE,"Hello, world"); gotoxy_(0,0); setattr(LMAGENTA|_RED,5); ------------------------------------------------------------------------ NAME setcursz DESCRIPTION Sets the cursor size. This function is video adapter dependent. SYNOPSIS #include "cxlvid.h" void setcursz(int sline,int eline); INPUTS sline - start line of cursor, 32 = no cursor eline - end line of cursor ALSO SEE getcursz hidecur lgcursor showcur smcursor EXAMPLE setcursz(1,7); /* sets cursor to large block on color displays */ ------------------------------------------------------------------------ NAME setkbloop DESCRIPTION Most of the time your program is idle, it is waiting for a keypress. This function allows you to set up a function that will be called 50 while waiting for a keypress. For example, you could update a status line, or update a time clock continuously while waiting for a keypress. SYNOPSIS #include "cxlkey.h" void setkbloop(void (*func)(void)); INPUTS func - address of the function to be called while waiting for keypress or NULL to cancel the procedure. ALSO SEE waitkey waitkeyt ------------------------------------------------------------------------ NAME setlines DESCRIPTION Sets the number of lines on the display. The videoinit() function must have previously been called. SYNOPSIS #include "cxlvid.h" int setlines(int numlines); INPUTS numlines - the number of lines to set the display to. Valid numbers are: 25 - all video adapters 43 - EGA 50 - VGA RETURN VALUE Nonzero if an error occurred. ALSO SEE mode videoinit vidtype EXAMPLE printf("%s\n",setlines(43)?"You do not have an EGA card": "You are now in EGA 43-line mode"); ------------------------------------------------------------------------ NAME setonkey DESCRIPTION Attaches/detaches a keypress to a function call. Works by intercepting any calls to CXL keyboard input functions. Whenever you use one of CXL's keyboard input functions, the input function 51 will check to see if the pressed key has been defined. If so, then the input function will call the corresponding function. If not, then the input function will pass on the keypress as normal. SYNOPSIS #include "cxlkey.h" int setonkey(unsigned keycode,void (*func) (void),unsigned pass); INPUTS keycode - keycode of key to define. If the keycode was previously defined, it will be re-defined. See Appendix B for a list of keycodes. func - address of the function to call upon keypress. If NULL is specified for func, then the specified keycode will be un-defined. pass - keycode of key to pass back to caller after the onkey function returns. This allows you to have one keypress return the code for another. If pass==0, then the key will not be passed back, and execution will resume where the interruption occurred. RETURN VALUE Nonzero if a memory allocation error occurred. ALSO SEE setkbloop EXAMPLE setonkey(0x011b,escape_routine,0); ------------------------------------------------------------------------ NAME showcur DESCRIPTION Reveals the hidden cursor, restoring it to its previous shape. SYNOPSIS #include "cxlvid.h" void showcur(void); ALSO SEE hidecur lgcursor setcursz smcursor ------------------------------------------------------------------------ NAME smcursor DESCRIPTION Makes the cursor small. SYNOPSIS 52 #include "cxlvid.h" void smcursor(void); ALSO SEE hidecur lgcursor setcursz showcur ------------------------------------------------------------------------ NAME sound_ DESCRIPTION Sounds a tone of specified pitch and duration. SYNOPSIS #include "cxldef.h" void sound_(unsigned pitch,unsigned duration); INPUTS pitch - pitch of tone (0-65535) duration - duration of tone (0-65535). ie. 182 = 10 seconds ALSO SEE beep EXAMPLE sound_(5000,36); /* sounds a tone for 2 seconds */ ------------------------------------------------------------------------ NAME spc DESCRIPTION Displays a specified number of spaces to the screen using the text attribute of the character under the cursor. SYNOPSIS #include "cxlvid.h" void spc(int num); INPUTS num - number of spaces to display ------------------------------------------------------------------------ NAME srestore DESCRIPTION Restores a previously saved screen, and frees the memory allocated by ssave(). SYNOPSIS 53 #include "cxlvid.h" void srestore(int *sbuf); INPUTS sbuf - address of previously saved screen buffer ALSO SEE ssave ------------------------------------------------------------------------ NAME ssave DESCRIPTION Saves the current screen to a buffer. To work with monochrome video adapters, videoinit() must have previously been called. SYNOPSIS #include "cxlvid.h" int *ssave(void); RETURN VALUE Address of newly created screen buffer or NULL if a memory allocation error occurred. ALSO SEE scrntodisk srestore videoinit wsave EXAMPLE int *p; if((p=ssave())==NULL) { printf("Memory allocation error\n"); exit(1); } ------------------------------------------------------------------------ NAME strblank DESCRIPTION Determines if a given string is blank (whitespace). SYNOPSIS #include "cxlstr.h" int strblank(char *str); INPUTS str - address of the string to check RETURN VALUE A zero if the string is not blank, otherwise it is. 54 EXAMPLE char string1[]=" Hello "; char string2[]=" \n \t \r "; printf("string1 is %sblank\n",strblank(string1)?"":"not "); printf("string2 is %sblank\n",strblank(string2)?"":"not "); ------------------------------------------------------------------------ NAME strbmatch DESCRIPTION Returns the best match of a string in an array of strings. SYNOPSIS #include "cxlstr.h" char *strbmatch(char *str,char *strarr[]); INPUTS str - address of string to match strarr - address of array of string pointers. The last pointer in the array must be NULL. RETURN VALUE Address of the string in the array that best matched the given string. ALSO SEE strmatch EXAMPLE char *strings[]= { "Hello","There","Computer","World",NULL }; char str1[]="xhelpx"; printf("<%s> best matches <%s>\n",str1,strbmatch(str1,strings)); ------------------------------------------------------------------------ NAME strchg DESCRIPTION Finds all letters in a string matching one character and replaces them with another. SYNOPSIS #include "cxlstr.h" int strchg(char *str,int oldch,int newch); INPUTS str - address of string to search oldch - character to search for newch - character to replace with RETURN VALUE 55 The number of matches found. ALSO SEE strichg EXAMPLE char str[]="Hello, world"; printf("Before: %s\n",str); strchg(str,'l','z'); printf("After: %s\n",str); ------------------------------------------------------------------------ NAME strchksum DESCRIPTION Returns the checksum of a string. The checksum is calculated by adding up the ASCII values of each character in the string. SYNOPSIS #include "cxlstr.h" unsigned long strchksum(char *str); INPUTS str - address of the string RETURN VALUE The checksum of the input string. ALSO SEE strichksum EXAMPLE printf("The checksum of <Hello> is %lu\n",strchksum("Hello")); ------------------------------------------------------------------------ NAME strcode DESCRIPTION Encrypts/decrypts a string. Call this function to encrypt a string, then call again using the same key to decrypt it. When reading or writing from a disk file, be sure to open the file in binary mode. SYNOPSIS #include "cxlstr.h" char *strcode(char *str,char *key); INPUTS str - the address of the string to encrypt/decrypt key - the address of the key string to encrypt/decrypt with. The string can consist of any valid characters (01-FF) and can be 56 of any length. Remember this key or your data will be lost forever! RETURN VALUE The address of the encrypted/decrypted string. ALSO SEE fcrypt EXAMPLE char str[]="Hello, world"; printf("Before: %s\n",str); strcode(str,"34&*#Mdq"); printf("Encrypted: %s\n",str); strcode(str,"34&*#Mdq"); printf("Decrypted: %s\n",str); ------------------------------------------------------------------------ NAME strdel DESCRIPTION Deletes a substring from within a string. SYNOPSIS #include "cxlstr.h" char *strdel(char *substr,char *str); INPUTS substr - address of substring to delete str - address of string to delete substring from RETURN VALUE A NULL if the substring was not found, or the address of the modified string. ALSO SEE stridel strinc strins strmid EXAMPLE char str[]="Hello there, world"; printf("Before: %s\n",str); strdel(" there",str); printf("After: %s\n",str); ------------------------------------------------------------------------ NAME strichg DESCRIPTION Finds all letters in a string matching one character and replaces them with another. Ignores case of letters. 57 SYNOPSIS #include "cxlstr.h" int strichg(char *str,int oldch,int newch); INPUTS str - address of string to search oldch - character to search for newch - character to replace oldch with RETURN VALUE The number of matches found. ALSO SEE strchg EXAMPLE char str[]="HelLo, worLd"; printf("Before: %s\n",str); strichg(str,'l','l'); printf("After: %s\n",str); ------------------------------------------------------------------------ NAME strichksum DESCRIPTION Returns the checksum of a string. The checksum is calculated by adding up the ASCII values of each character in the string. All lowercase letters will be counted as uppercase. SYNOPSIS #include "cxlstr.h" unsigned long strichksum(char *str); INPUTS str - address of the string RETURN VALUE The checksum of the input string. ALSO SEE strchksum EXAMPLE printf("The checksum of <Hello> is %lu\n",strichksum("Hello")); ------------------------------------------------------------------------ NAME stridel DESCRIPTION Deletes a substring from within a string. Ignores case of letters. 58 SYNOPSIS #include "cxlstr.h" char *stridel(char *substr,char *str); INPUTS substr - address of substring to delete str - address of string to delete substring from RETURN VALUE A NULL if the substring was not found, or the address of the modified string. ALSO SEE strdel striinc EXAMPLE char str[]="Hello tHeRe, world"; printf("Before: %s\n",str); stridel(" ThErE",str); printf("After: %s\n",str); ------------------------------------------------------------------------ NAME striinc DESCRIPTION Determines if and where one string is included within another. Ignores case of letters. SYNOPSIS #include "cxlstr.h" char *striinc(char *str1,char *str2); INPUTS str1 - address of the string to search for str2 - address of the string to search RETURN VALUE The address where string1 is included in string2, or a NULL if string1 is not included in string2. ALSO SEE strinc strmid EXAMPLE char str[]="Hello, world"; printf("<ElLo> is %sincluded in <%s>\n" ,striinc("ElLo",str)==NULL?"not ":"",str); ------------------------------------------------------------------------ NAME strinc 59 DESCRIPTION Determines if and where one string is included within another. SYNOPSIS #include "cxlstr.h" char *strinc(char *str1,char *str2); INPUTS str1 - address of the string to search for str2 - address of the string to search RETURN VALUE The address where string1 is included in string2, or a NULL if string1 is not included in string2. ALSO SEE striinc strmid EXAMPLE char str[]="Hello, world"; printf("<ElLo> is %sincluded in <%s>\n" ,strinc("ElLo",str)==NULL?"not ":"",str); ------------------------------------------------------------------------ NAME strins DESCRIPTION Inserts one string into another. SYNOPSIS #include "cxlstr.h" char *strins(char *instr,char *str,int st_pos); INPUTS instr - the address of the string to insert str - the address of the string to insert instr into. This area must be large enough to hold the size of the modified string. st_pos - the starting position of where to insert RETURN VALUE The address of the modified string. ALSO SEE strdel strinc EXAMPLE char str[20]="Hello, world"; printf("Before: %s\n",str); strins(" there",str,5); printf("After: %s\n",str); 60 ------------------------------------------------------------------------ NAME striocc DESCRIPTION Returns the number of occurrences of a character in a string. Ignores case of letters. SYNOPSIS #include "cxlstr.h" int striocc(char *str,int ch); INPUTS str - address of the string to search ch - the character to look for RETURN VALUE The number of occurrences of the character in the string. ALSO SEE strocc EXAMPLE char str[]="HelLo, world"; printf("There are %d occurrences of '%c' in <%s>\n" ,striocc(str,'l'),'l',str); ------------------------------------------------------------------------ NAME strisocc DESCRIPTION Counts occurrences of one string within another. Ignores case of letters. SYNOPSIS #include "cxlstr.h" int strisocc(char *str1,char *str2); INPUTS str1 - address of string to search for str2 - address of string to search RETURN VALUE The number of times that string str1 occurs in string str2. ALSO SEE strsocc EXAMPLE char str1[]="hello"; char str2[]="Hello1HELLO2HeLlO3hElLo"; 61 printf("<%s> occurs in <%s> %d times\n",str1,str2 ,strisocc(str1,str2)); ------------------------------------------------------------------------ NAME strisrep DESCRIPTION Searches for, and replaces one string within another. Ignores case of letters. SYNOPSIS #include "cxlstr.h" char *strisrep(char *str,char *search,char *replace); INPUTS str - address of string to search. This must have enough space to hold the modified string. search - address of string to search for replace - address of string to replace search string with RETURN VALUE The address of the modified string, or NULL if the search string wasn't found. ALSO SEE strsrep EXAMPLE char str[24]="This is a big string"; printf("Before: %s\n",str); strisrep(str,"StR","th"); printf("After: %s\n",str); ------------------------------------------------------------------------ NAME strleft DESCRIPTION Takes a specified portion of a string from its left and creates a new string. SYNOPSIS #include "cxlstr.h" char *strleft(char *str,int num_chars); INPUTS str - address of input string num_chars - number of characters to copy RETURN VALUE Address of the newly created string or a NULL if a memory allocation 62 error occurred. Be sure to free() this string if or when you don't need it anymore. ALSO SEE strmid strright strtrim EXAMPLE char *p,str[]="Hello, world"; printf("%s\n",p=strleft(str,5)); free(p); ------------------------------------------------------------------------ NAME strljust DESCRIPTION Left justifies a text string. SYNOPSIS #include "cxlstr.h" char *strljust(char *str); INPUTS str - address of the string to left justify RETURN VALUE Address of the modified string. ALSO SEE strrjust EXAMPLE char str[]=" Hello, world"; printf("Before: <%s>\n",str); strljust(str); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME strltrim DESCRIPTION Trims the leading spaces off of a string. SYNOPSIS #include "cxlstr.h" char *strltrim(char *str); INPUTS str - address of the string to trim RETURN VALUE 63 Address of the modified string. ALSO SEE strright strsetsz strtrim EXAMPLE char str[]=" Hello, world"; printf("Before: <%s>\n",str); strltrim(str); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME strmatch DESCRIPTION Compares 2 strings and returns a match score. SYNOPSIS #include "cxlstr.h" int strmatch(char *str1,char *str2); INPUTS str1 - address of first string str2 - address of second string RETURN VALUE A match score. The higher the score, the better they match. ALSO SEE strbmatch ------------------------------------------------------------------------ NAME strmid DESCRIPTION Takes a section from input string starting at given position and taking the given amount of characters creating a new string. SYNOPSIS #include "cxlstr.h" char *strmid(char *str,int st_pos,int num_chars); INPUTS str - address of input string st_pos - position in input string to start copying characters (starting at position 0) num_chars - number of characters to copy RETURN VALUE Address of the newly created string or a NULL if a memory allocation 64 error occurred. Be sure to free() the string when or if you are finished with it. ALSO SEE strleft strright EXAMPLE char *p,str[]="Hello there, world"; printf("%s\n",p=strmid(str,6,5)); free(p); ------------------------------------------------------------------------ NAME strocc DESCRIPTION Returns the number of occurrences of a given character in a string. SYNOPSIS #include "cxlstr.h" int strocc(char *str,int ch); INPUTS str - address of the string to search ch - the character to look for RETURN VALUE The number of occurrences of the given character in the string. ALSO SEE striocc EXAMPLE char str[]="Hello, world"; printf("There are %d occurrences of '%c' in <%s>\n" ,strocc(str,'l'),'l',str); ------------------------------------------------------------------------ NAME strright DESCRIPTION Takes a specifed portion from the right side of a string creating a new string. SYNOPSIS #include <string.h> #include "cxlstr.h" char *strright(char *str,int num_chars); INPUTS str - address of input string 65 num_chars - number of characters to copy RETURN VALUE Address of the newly created string or a NULL if a memory allocation error occurred. Be sure to free() the string when or if you are finished with it. ALSO SEE strleft strltrim strmid EXAMPLE char *p,str[]="Hello, world"; printf("%s\n",p=strright(str,5)); free(p); ------------------------------------------------------------------------ NAME strrjust DESCRIPTION Right justifies a text string. SYNOPSIS #include "cxlstr.h" char *strrjust(char *str); INPUTS str - address of string to right justify RETURN VALUE Address of modified string. ALSO SEE strljust EXAMPLE char str[]="Hello, world "; printf("Before: <%s>\n",str); strrjust(str); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME strrol DESCRIPTION Rotates a string specified number of characters left. The rotated characters wrap around to the right side of the string. SYNOPSIS #include "cxlstr.h" char *strrol(char *str,int count); 66 INPUTS str - the address of the string to rotate count - number of characters to rotate RETURN VALUE The address of the modified string. ALSO SEE strror strshl EXAMPLE char str[]="Hello, world"; printf("Before: <%s>\n",str); strrol(str,3); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME strror DESCRIPTION Rotates a string specified number of characters right. The rotated characters wrap around to the left side of the string. SYNOPSIS #include "cxlstr.h" char *strror(char *str,int count); INPUTS str - the address of the string to rotate count - number of characters to rotate RETURN VALUE The address of the modified string. ALSO SEE strrol strshr EXAMPLE char str[]="Hello, world"; printf("Before: <%s>\n",str); strror(str,3); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME strsetsz DESCRIPTION Adjusts the length of a string, either by truncation or padding with spaces. 67 SYNOPSIS #include "cxlstr.h" char *strsetsz(char *str,int newsize); INPUTS str - address of the string to modify. This area must be large enough to hold the string at its newsize length. newsize - the new length of the string RETURN VALUE The address of the modified string. ALSO SEE strtrim EXAMPLE char str[22]="Hello, world"; printf("Before: <%s>\n",str); strsetsz(str,20); printf("Len=20: <%s>\n",str); strsetsz(str,5); printf("Len=5: <%s>\n",str); ------------------------------------------------------------------------ NAME strshl DESCRIPTION Shifts a string a specified number of characters left. Characters that shift past the beginning of the string "drop off" and spaces are added to the right of the string. SYNOPSIS #include "cxlstr.h" char *strshl(char *str,int count); INPUTS str - the address of the string to shift count - number of characters to shift RETURN VALUE The address of the modifed string. ALSO SEE strrol strshr EXAMPLE char str[]="Hello, world"; printf("Before: <%s>\n",str); strshl(str,3); printf("After: <%s>\n",str); ------------------------------------------------------------------------ 68 NAME strshr DESCRIPTION Shifts a string a specified number of characters right. Characters that shift past the end of the string "drop off" and spaces are added to the left of the string. SYNOPSIS #include "cxlstr.h" char *strshr(char *str,int count); INPUTS str - the address of the string to shift count - number of characters to shift RETURN VALUE The address of the modified string. ALSO SEE strror strshl EXAMPLE char str[]="Hello, world"; printf("Before: <%s>\n",str); strshr(str,3); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME strsocc DESCRIPTION Counts the occurrences of one string within another. SYNOPSIS #include "cxlstr.h" int strsocc(char *str1,char *str2); INPUTS str1 - address of string to search for str2 - address of string to search RETURN VALUE The number of times that string str1 occurs in string str2. ALSO SEE strisocc EXAMPLE char str1[]="hello"; char str2[]="Hello1hello2HeLlO3hElLo"; printf("<%s> occurs in <%s> %d times\n",str1,str2 69 ,strsocc(str1,str2)); ------------------------------------------------------------------------ NAME strsrep DESCRIPTION Searches for, and replaces one string within another. SYNOPSIS #include "cxlstr.h" char *strsrep(char *str,char *search,char *replace); INPUTS str - address of string to search search - address of string to search for replace - address of string to replace search string with RETURN VALUE The address of the modified string, or NULL if the search string wasn't found. ALSO SEE strisrep EXAMPLE char str[24]="This is a big string"; printf("Before: %s\n",str); strsrep(str,"str","th"); printf("After: %s\n",str); ------------------------------------------------------------------------ NAME strtrim DESCRIPTION Trims trailing spaces off of a string. SYNOPSIS #include "cxlstr.h" char *strtrim(char *str); INPUTS str - address of the string to trim RETURN VALUE Address of the modified string. ALSO SEE strleft strltrim strsetsz EXAMPLE 70 char str[]="Hello, world "; printf("Before: <%s>\n",str); strtrim(str); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME struplow DESCRIPTION Converts a string to mixed upper & lowercase characters. Characters are forced to upper or lowercase depending upon the previous character in the string. SYNOPSIS #include "cxlstr.h" char *struplow(char *str); INPUTS str - the address of the string to convert RETURN VALUE The address of the modified string. ALSO SEE touplow EXAMPLE char str[]="hElLo, wOrLd"; printf("Before: <%s>\n",str); struplow(str); printf("After: <%s>\n",str); ------------------------------------------------------------------------ NAME sysdate DESCRIPTION Returns a string containing the current system date. SYNOPSIS #include "cxldef.h" char *sysdate(int dtype); INPUTS dtype - date type code. Can be one of the following: Code Example ---- ------- 0 December 3, 1988 1 3 Dec 88 2 12-3-88 3 12/3/88 71 4 3/12/88 RETURN VALUE The address of the static string containing the system date. ALSO SEE systime EXAMPLE printf("Today's date is %s\n",sysdate(0)); ------------------------------------------------------------------------ NAME systime DESCRIPTION Returns a string containing the current system time. SYNOPSIS #include "cxldef.h" char *systime(int ttype); INPUTS ttype - time type code. Can be one of the following: Code Example ---- ------- 0 16:30:57.89 1 16:30:57 2 4:30 PM 3 4:30p 4 4:30 RETURN VALUE The address of the static string containing the current system time. ALSO SEE sysdate EXAMPLE printf("The current time is %s\n",systime(2)); ------------------------------------------------------------------------ NAME tabstop DESCRIPTION Calculates a tab stop from given column and tab width. SYNOPSIS #include "cxldef.h" int tabstop(int col,int tabwidth); 72 INPUTS col - column tabwidth - tab width RETURN VALUE The next tab stop column. EXAMPLE printf("The next tab stop after column 9 is column %d\n" ,tabstop(9,8)); ------------------------------------------------------------------------ NAME timer DESCRIPTION Returns the value of the BIOS timer. This value is incremented by one every 18.2 seconds. SYNOPSIS #include "cxldef.h" unsigned long timer(void); RETURN VALUE Current value of the BIOS timer. ALSO SEE delay_ EXAMPLE printf("Time #1: %lu\n",timer()); delay_(36); printf("Time #2: %lu\n",timer()); ------------------------------------------------------------------------ NAME touplow DESCRIPTION Converts a character to upper or lowercase depending on previous character. This function is used internally by other CXL functions. SYNOPSIS #include "cxlstr.h" int touplow(char *str,char *pos,int ch); INPUTS str - address of string pos - address of current position in string ch - character to convert RETURN VALUE 73 The converted character. ALSO SEE struplow EXAMPLE char ch='w',str[20]="Hello, "; printf("The character '%c' will be appended to <%s> as '%c'\n" ,ch,str,touplow(str,str+7,ch)); ------------------------------------------------------------------------ NAME videoinit DESCRIPTION Initializes CXL's video system. By default, all CXL functions performing direct screen writes go to the CGA screen memory at address B800:0000. If you want these functions to work correctly with a monochrome video adapter or within a DESQview window, you must call this function. This function sets the values in the global structure variable _vinfo. SYNOPSIS #include "cxlvid.h" int videoinit(void); RETURN VALUE Video adapter type. See the vidtype() description for all the possible return values. ALSO SEE vidtype ------------------------------------------------------------------------ NAME vidtype DESCRIPTION Determines the display adapter type. SYNOPSIS #include "cxlvid.h" int vidtype(void); RETURN VALUE Video adapter type. Will be one of the following values: V_NONE - no video adapter V_MDA - Monochrome Display Adapter V_EGAMONO - Enhanced Graphics Adapter in mono mode V_MCGAMONO - Multi-Color Graphics Array adapter in mono mode V_VGAMONO - Video Graphics Array adapter in mono mode V_HGC - Hercules Graphics Card 74 V_HGCPLUS - Hercules Graphics Card Plus V_INCOLOR - Hercules InColor Card V_CGA - Color Graphics Adapter V_EGA - Enhanced Graphics Adapter V_MCGA - Multi-Color Graphics Array adapter V_VGA - Video Graphics Array adapter ALSO SEE mode videoinit ------------------------------------------------------------------------ NAME wactiv DESCRIPTION Activates a previously opened window, bringing it "in front" of all the others. Many windowing functions can perform their operations only on the active window. If a window is not active, you will need to activate it before you can use it for these functions. SYNOPSIS #include "cxlwin.h" int wactiv(WINDOW whandle); INPUTS whandle - the window handle of the window to activate RETURN VALUE W_NOERROR - no error W_NOTFOUND - window handle not found W_NOACTIVE - no open windows ALSO SEE wisactiv wopen EXAMPLE int w1,w2; w1=wopen(10,10,20,40,0,LCYAN|_BLUE,LCYAN|_BLUE); w2=wopen(0,0,15,35,1,LMAGENTA|_RED,LMAGENTA|_RED); wactiv(w1); ------------------------------------------------------------------------ NAME waitkey DESCRIPTION Clears the keyboard buffer and halts program execution until a key is pressed. SYNOPSIS #include "cxlkey.h" int waitkey(void); 75 RETURN VALUE The ASCII value of the key pressed. ALSO SEE clearkeys getchf waitkeyt EXAMPLE printf("Press any key to continue...."); waitkey(); ------------------------------------------------------------------------ NAME waitkeyt DESCRIPTION Clears the keyboard buffer and halts program execution until a key is pressed or the specified time limit expires. SYNOPSIS #include "cxlkey.h" int waitkeyt(int duration); INPUTS duration - length of time to wait for keypress (ie. 182 = 10 secs.) RETURN VALUE The ASCII value of the key pressed or a -1 if the time limit expired. ALSO SEE clearkeys delay_ getchf waitkey EXAMPLE printf("Press any key to continue...."); waitkeyt(91); /* time out after 5 seconds */ ------------------------------------------------------------------------ NAME wborder DESCRIPTION Changes the active window's border box type. If changing to or from a borderless window, the window's effective area will change as well, changing relative coordinates within the window. SYNOPSIS #include "cxlwin.h" int wborder(int btype); INPUTS btype - box type. Can be one of the following: 0 - single line border 76 1 - double line border 2 - single horz, double vert line border 3 - double horz, single vert line border 4 - thick line border 5 - no border (uses spaces for border chars) RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVBTYPE - invalid box type ------------------------------------------------------------------------ NAME wbox DESCRIPTION "Draws" a text box in the active window. SYNOPSIS #include "cxlwin.h" int wbox(int wsrow,int wscol,int werow,int wecol,int btype, int attr); INPUTS wsrow - window start row of box wscol - window start column of box werow - window end row of box wecol - window end column of box btype - box type. Can be one of the following: 0 - single line border 1 - double line border 2 - single horz, double vert line border 3 - double horz, single vert line border 4 - thick line border 5 - no border (uses spaces for border chars) attr - text attribute to use for box characters RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates ALSO SEE wfill whline wvline ------------------------------------------------------------------------ NAME wcclear DESCRIPTION Clears the active window using specified text attribute, then homes the cursor. 77 SYNOPSIS #include "cxlwin.h" int wcclear(int attr); INPUTS attr - text attribute to clear window with RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wclear wclreol wclreos wfillch EXAMPLE wcclear(BLACK|_BLACK); ------------------------------------------------------------------------ NAME wcenters DESCRIPTION Displays a string centered in active window. Does not recognize control characters. Does not update cursor position. SYNOPSIS #include "cxlwin.h" int wcenters(int wrow,int attr,char *str); INPUTS wrow - window row to center string at attr - text attribute to use for displayed characters str - address of string to display RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid window row W_STRLONG - string too long to be centered in window ALSO SEE wprints wrjusts EXAMPLE wcenters(2,YELLOW|_LGREY,"Main Menu"); ------------------------------------------------------------------------ NAME wchgattr DESCRIPTION Changes the text attribute of the active window. All text within 78 the window will be changed also. SYNOPSIS #include "cxlwin.h" int wchgattr(int battr,int wattr); INPUTS battr - the attribute to make the window's border wattr - the attribute to make the window RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wtextattr EXAMPLE wchgattr(LMAGENTA|_RED,LCYAN|_BLUE); ------------------------------------------------------------------------ NAME wchkbox DESCRIPTION Determines whether input window box coordinates are valid for use in the active window. SYNOPSIS #include "cxlwin.h" int wchkbox(int wsrow,int wscol,int werow,int wecol); INPUTS wsrow - window start row wscol - window start column werow - window end row wecol - window end column RETURN VALUE Nonzero if input window box coordinates are invalid. ALSO SEE wchkcol wchkcoord wchkrow ------------------------------------------------------------------------ NAME wchkcol DESCRIPTION Determines whether input window column coordinate is valid for use in the active window. 79 SYNOPSIS #include "cxlwin.h" int wchkcol(int wcol); INPUTS wcol - window column RETURN VALUE Nonzero if input window column coordinate is invalid. ALSO SEE wchkbox wchkcoord wchkrow ------------------------------------------------------------------------ NAME wchkcoord DESCRIPTION Determines whether input window row,column coordinates are valid for use in the active window. SYNOPSIS #include "cxlwin.h" int wchkcoord(int wrow,int wcol); INPUTS wrow - window row wcol - window column RETURN VALUE Nonzero if input window coordinates are invalid. ALSO SEE wchkbox wchkcol wchkrow ------------------------------------------------------------------------ NAME wchkrow DESCRIPTION Determines whether input window row is valid for use in the active window. SYNOPSIS #include "cxlwin.h" int wchkrow(int wrow); INPUTS wrow - window row RETURN VALUE Nonzero if input window row is invalid. 80 ALSO SEE wchkbox wchkcol wchkcoord ------------------------------------------------------------------------ NAME wclear DESCRIPTION Clears the active window, then homes the cursor. SYNOPSIS #include "cxlwin.h" int wclear(void); RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wcclear wclreol wclreos wfillch ------------------------------------------------------------------------ NAME wclose DESCRIPTION Closes the active window. If the window has a shadow, it will be closed as well. SYNOPSIS #include "cxlwin.h" int wclose(void); RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wcloseall wopen ------------------------------------------------------------------------ NAME wcloseall DESCRIPTION Closes all open windows. SYNOPSIS #include "cxlwin.h" int wcloseall(void); 81 RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wclose wopen ------------------------------------------------------------------------ NAME wclreol DESCRIPTION Clears from the cursor to the end of the active window's line. The cursor's position is not updated. SYNOPSIS #include "cxlwin.h" int wclreol(void); RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wclear wclreos wfillch ------------------------------------------------------------------------ NAME wclreos DESCRIPTION Clears from the cursor to the end of the active window. The cursor's position is not updated. SYNOPSIS #include "cxlwin.h" int wclreos(void); RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wclear wclreol wfillch ------------------------------------------------------------------------ NAME wcopy DESCRIPTION Creates a new window duplicating the active window. The new window 82 becomes the active window. SYNOPSIS #include "cxlwin.h" WINDOW wcopy(int nsrow,int nscol); INPUTS nsrow - start row of where to place the duplicate window nscol - start column of where to place the duplicate window RETURN VALUE The window handle of the new window. If an error occurred, a zero will be returned and the global variable _winfo.errno will be set to one of the following values: W_ALLOCERR - memory allocation error W_INVCOORD - invalid coordinates ALSO SEE wactiv wmove wopen EXAMPLE wopen(10,10,20,40,0,LCYAN|_BLUE,LCYAN|_BLUE); wcopy(0,0); ------------------------------------------------------------------------ NAME wdelline DESCRIPTION Deletes a line from the active window. Depending upon the input scroll direction, the lines above or below the line to delete will scroll to fill in the deleted line in, and a blank line will be added. If what you really want to do is clear the line, you may want to use wclreol() instead. SYNOPSIS #include "cxlwin.h" int wdelline(int wrow,int direc); INPUTS wrow - window row to delete direc - scroll direction. Can be one of the following: SUP - scroll up SDOWN - scroll down RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid window row ALSO SEE wclreol winsline wscroll 83 EXAMPLE wdelline(3,SUP); ------------------------------------------------------------------------ NAME wdump DESCRIPTION Dumps the active window to the default printer (PRN). SYNOPSIS #include "cxlwin.h" int wdump(void); RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE windump ------------------------------------------------------------------------ NAME wdupc DESCRIPTION Displays a character a specified number of times in the active window. Characters will be displayed in the window's current text attribute. Control characters are recognized. Cursor position is updated. SYNOPSIS #include "cxlwin.h" int wdupc(int ch,int count); INPUTS ch - character to be displayed count - number of times to display character RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wdups wputc wtextattr EXAMPLE wdupc('X',5); ------------------------------------------------------------------------ NAME 84 wdups DESCRIPTION Displays a string a specified number of times in the active window. Characters will be displayed in the window's current text attribute. Control characters are recognized. Cursor position is updated. SYNOPSIS #include "cxlwin.h" int wdups(char *str,int count); INPUTS str - character to be displayed count - number of times to display character RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wdupc wputs wtextattr EXAMPLE wdups("Hello ",3); ------------------------------------------------------------------------ NAME werrmsg DESCRIPTION Most of CXL's windowing functions set the global variable _winfo.errno before returning to their caller. This function, werrmsg(), reads _winfo.errno and returns the literal error message that corresponds to it. This can be very useful in debugging programs that use CXL's windowing functions. Check the individual windowing function descriptions to find out which ones actually set _winfo.errno. SYNOPSIS #include "cxlwin.h" char *werrmsg(void); RETURN VALUE The address of the static string containing the error message that corresponds to the window error code in _winfo.errno. ALSO SEE wperror EXAMPLE wgotoxy(255,255); /* invalid coordinates */ printf("Error = %s\n",werrmsg()); 85 ------------------------------------------------------------------------ NAME wfill DESCRIPTION Fills in a region of active window with a specified character and attribute. SYNOPSIS #include "cxlwin.h" int wfill(int wsrow,int wscol,int werow,int wecol,int ch,int attr); INPUTS wsrow - window start row wscol - window start column werow - window end row wecol - window end column ch - character to fill with attr - text attribute to use for fill RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates ALSO SEE wbox EXAMPLE wfill(2,3,5,15,'Z',WHITE|_GREEN); ------------------------------------------------------------------------ NAME wfillch DESCRIPTION Specifies which character the windowing system will use for filling windows with. By default, it is a space (' '). SYNOPSIS #include "cxlwin.h" void wfillch(int ch); INPUTS ch - character to fill with EXAMPLE wfillch('\260'); ------------------------------------------------------------------------ NAME 86 wfindrec DESCRIPTION Finds the address of a window record using the specified window handle. This is used internally be several CXL functions. SYNOPSIS #include "cxlwin.h" struct _wrec_t *wfindrec(WINDOW whandle); INPUTS whandle - window handle of window record to find RETURN VALUE The address of the found window record, or NULL if no record was found for the given handle. ------------------------------------------------------------------------ NAME wgetc DESCRIPTION Gets a character from the keyboard. Entered character will be echoed to the active window using the window's current text attribute. Cursor position is updated. SYNOPSIS #include "cxlwin.h" int wgetc(void); RETURN VALUE The ASCII value of the key pressed or a zero if an error occurred. If error, the global variable _winfo.errno will be set to one of the following: W_NOACTIVE - no active window ALSO SEE wgetchf wscanf wtextattr ------------------------------------------------------------------------ NAME wgetchf DESCRIPTION Gets a character from the keyboard. Allows input only of characters listed in the string of valid characters. Entered characters will be echoed to the active window using the text attribute set by the wtextattr() function. Cursor position is updated. Escape checking is provided by default. This can be turned off with the wsetesc() function. SYNOPSIS 87 #include "cxlwin.h" int wgetchf(char *valid,int defchar); INPUTS valid - address of the string containing the valid characters defchar - default selection in case [Enter] is pressed, or a zero for none RETURN VALUE The ASCII value of the key pressed, or a zero if an error occurred. If error, the global variable _winfo.errno will be set to one of the following: W_NOACTIVE - no active window W_ESCPRESS - [Esc] key was pressed ALSO SEE wgetc wscanf wtextattr EXAMPLE int ch; wputs("Quit, are you sure? "); if((ch=wgetchf("YyNn",'N'))==0) wprintf("Error: %s\n",werrmsg()); ------------------------------------------------------------------------ NAME wgetns DESCRIPTION Gets a string from the keyboard, limiting the number of characters input to the specified length. Entered characters will be echoed to the active window using the text attribute set by the wtextattr() function. Cursor position is updated. Escape checking is provided by default. This can be turned off with the wsetesc() function. SYNOPSIS #include "cxlwin.h" int wgetns(char *str,int maxlen); INPUTS str - address of the buffer to receive the input string maxlen - the maximum length of the input string RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_ESCPRESS - [Esc] key was pressed ALSO SEE wgets winputsf wscanf wsetesc wtextattr EXAMPLE char buf[6]; wputs("Enter 5 characters: "); 88 if(wgetns(buf,5)) wprintf("Error: %s\n",werrmsg()); ------------------------------------------------------------------------ NAME wgets DESCRIPTION Gets a string from the keyboard. Entered characters will be echoed to the active window in the text attribute set by the wtextattr() function. Cursor position is updated. SYNOPSIS #include "cxlwin.h" int wgets(char *str); INPUTS str - the address of the buffer to receive the input string RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wgetns winputsf wscanf wtextattr EXAMPLE char name[30]; wputs("Enter your name: "); wgets(name); ------------------------------------------------------------------------ NAME wgotoxy DESCRIPTION Sets cursor coordinates within the active window. SYNOPSIS #include "cxlwin.h" int wgotoxy(int wrow,int wcol); INPUTS wrow - window row (Y coordinate) wcol - window column (X coordinate) RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates ALSO SEE wpgotoxy wreadcur 89 ------------------------------------------------------------------------ NAME whandle DESCRIPTION Returns the window handle of the active window. SYNOPSIS #include "cxlwin.h" WINDOW whandle(void); RETURN VALUE The handle of the active window or zero if error. If error, the global variable _winfo.errno will be set to one of the following: W_NOACTIVE - no active window ALSO SEE wactiv wisactiv ------------------------------------------------------------------------ Context-Sensitive Help Functions CXL's context-sensitive help system operates on the principle of a current help category and a help category stack. Both require some explaining before you begin to use them. The current help category is the one that will be used when the user presses the help key. It can be set by one of several ways. The direct way is for you to explicitly set it by calling whelpcat(). There are also indirect ways that the current help category can be set. Windows, input fields, and menu items each have individual help categories as part of their record. If you were to activate a window which has its own help category, then that would become the current help category. During the processing of input fields and menus, each time you move to a new field or menu item item, the current help category is set to the whatever the field/item's help category is, even if that category is zero (empty). This means that input forms and menus overwrite what was in the current help category before the form/menu began processing. To keep from losing the current help category during the processing of forms and menus, you need to be able to save the current help category during that period. This is where the help stack comes into the picture. To save the current help category, you push it onto the stack with whelpush(). When you need to retrieve it, you pop it back off of the stack using whelpop(). The category popped off of the stack then becomes the current help category. This help stack is a LIFO (Last In First Out) stack and holds up to 20 help categories. When the help key is pressed by the user, CXL's help processor will search the help file for the current help category. If the current help category is zero (empty), then the help category off top of the stack will be used. This is where the help stack comes in handy. It allows 90 you to have a "backup" help category for menu items and fields that don't have help categories of their own. Before processing of the form or menu, you simply push the background help category onto the stack. When the help category is found in the help file, the corresponding help text will be displayed on the screen in the help window. If there is more than 1 page of text, the user can change between pages via the [PgUp]/[PgDn] keys. If there are cross-reference items, the user can use the arrow keys to move between them, and use [Enter] to select. Pressing [Esc] will exit the help window. Creating help files is quite easy. You need to have an ASCII editor to create them with. Your help file can contain several help categories. Here is an example of a couple of defined help categories: *B 1,Help Category 1 help text help text help text help text help text help text help text help text help text *P help text help text help text help text help text help text help text help text help text *E *B 2,Help Category 2 help text help text help text help text help text help text help text help text help text *P help text help text help text help text help text help text help text help text help text Also see: ^Help Category 1^ *E The "*B" indicator specifies the beginning of a help category. The format is "*B helpcatnumber,helpcatname". The help category number is the number of the help category that you set using whelpcat(). The "*P" indicator specifies a page break and is optional. You may have as many page breaks as you'd like. The "*E" indicator specifies the end of the help category. The "*B", "*P", and "*E" indicators must begin in the first column. These indicators and the help category name are case insensitive (can be in lowercase, upper case, or mixed). In the definition of Help Category 2, you will notice the cross- reference to Help Category 1. All cross-referencing is done by embedding the cross-reference category name (not number) inside carats (^). If you need to display a carat inside the help file, use a double carat (^^). Any text contained outside of the "*B" and "*E" will be treated as comments. If an "*E" is not found, then the end-of-file will be treated as an "*E". 91 Now, you need to "compile" your ASCII help file into an indexed file. There is utility, MAKEINDX.COM, which takes your ASCII help file as input, and outputs an indexed version of of the same file. This new file is the actual help file that you specify in the whelpdef() function. Keep the ASCII help file around so you will be able to make modifications. ------------------------------------------------------------------------ NAME whelpcat DESCRIPTION Sets the current help category. If a window is active at the time, it will also set that window's help category. The help category set by calling this function is what will be used by the help processor for searching the help file for help text. SYNOPSIS #include "cxlwin.h" int whelpcat(int cat); INPUTS cat - help category number RETURN VALUE W_NOERROR - no error W_NOHLPDEF - no help record defined ALSO SEE whelpclr whelpdef whelpop whelpush ------------------------------------------------------------------------ NAME whelpclr DESCRIPTION Clears the help category stack. SYNOPSIS #include "cxlwin.h" int whelpclr(void); RETURN VALUE W_NOERROR - no error W_NOHLPDEF - no help defined ALSO SEE whelpdef whelpcat whelpop whelpush ------------------------------------------------------------------------ NAME 92 whelpdef DESCRIPTION Defines the help file, key, and window colors. After calling this function, anytime the help key is pressed, the help processor will search the help file for whatever the current help category is. SYNOPSIS #include "cxlwin.h" int whelpdef(char *file,unsigned key,int winattr,int textattr, int selattr,int barattr,void (*open)(void)); INPUTS file - address of string containing help file name key - keycode of key to be used for help key. See Appendix B for a list of keycodes that you can use. winattr - attribute of the help window. textattr - attribute of the text in the help window. selattr - attribute of the cross-reference selection text. barattr - attribute of the cross-reference selection bar. open - address of the function to call immediately upon opening of the help window. This can be used to call a function that could add a window shadow, etc. If you do not need to use this feature, specify NULL. RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error ALSO SEE whelpcat EXAMPLE whelpdef("CXLDEMO.HLP",0x3b00,LCYAN|_BLUE,GREEN|_BLUE,LGREEN|_BLUE ,BLUE|_LGREY,NULL); ------------------------------------------------------------------------ NAME whelpop DESCRIPTION Pops the help category off of the top of the stack and makes it the current help category. SYNOPSIS #include "cxlwin.h" int whelpop(void); RETURN VALUE W_NOERROR - no error W_NOHLPDEF - no defined help, see whelpdef(). W_HLPSTKUN - help stack underflow (stack empty). 93 ALSO SEE whelpcat whelpclr whelpdef whelpopc whelpush whelpushc ------------------------------------------------------------------------ NAME whelpopc DESCRIPTION Pops the help category off of the top of the stack and into the void. The current help category is not affected. SYNOPSIS #include "cxlwin.h" int whelpopc(void); RETURN VALUE W_NOERROR - no error W_NOHLPDEF - no defined help, see whelpdef(). W_HLPSTKUN - help stack underflow (stack empty). ALSO SEE whelpcat whelpclr whelpdef whelpop whelpush whelpushc ------------------------------------------------------------------------ NAME whelpush DESCRIPTION Pushes the current help category onto the help category stack. The stack can hold up to 20 help categories. SYNOPSIS #include "cxlwin.h" int whelpush(void); RETURN VALUE W_NOERROR - no error W_NOHLPDEF - no defined help. See whelpdef(). W_HLPSTKOV - help stack overflow (stack full). ALSO SEE whelpcat whelpclr whelpdef whelpop whelpopc whelpushc ------------------------------------------------------------------------ NAME whelpushc DESCRIPTION Pushes the specified help category onto the help category stack. The current help category is not affected. The stack can hold up to 20 help categories. 94 SYNOPSIS #include "cxlwin.h" int whelpushc(int cat); INPUTS cat - help category number to push onto help category stack RETURN VALUE W_NOERROR - no error W_NOHLPDEF - no defined help. See whelpdef(). W_HLPSTKOV - help stack overflow (stack full). ALSO SEE whelpcat whelpclr whelpdef whelpop whelpopc whelpush ------------------------------------------------------------------------ NAME whide DESCRIPTION Hides the active window. The next window becomes active. SYNOPSIS #include "cxlwin.h" int whide(void); RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window ALSO SEE whandle wunhide ------------------------------------------------------------------------ NAME whline DESCRIPTION "Draws" a horizontal text line in active window using characters defined by given box type. If horizontal line crosses a vertical line of the same box type, an appropriate intersection or corner will be used. SYNOPSIS #include "cxlwin.h" int whline(int wsrow,int wscol,int count,int btype,int attr); INPUTS wsrow - window start row wscol - window start column count - number of line characters to display 95 btype - box type. Can be one of the following: 0 - single line 1 - double line 2 - single horz, double vert line 3 - double horz, single vert line 4 - thick line 5 - uses spaces for line chars attr - text attribute to use for the line RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - text line too long for window W_INVBTYPE - invalid box type ALSO SEE wvline EXAMPLE whline(1,0,5,LMAGENTA|_BLACK); ------------------------------------------------------------------------ NAME windowat DESCRIPTION Returns the handle of the window at given screen row,column coordinates. SYNOPSIS #include "cxlwin.h" WINDOW windowat(int row,int col); INPUTS row - screen row col - screen column RETURN VALUE The window handle of the window found at given coordinates. If an error occurred, zero will be returned and _winfo.errno will be set to one of the following: W_NOACTIVE - no active window W_NOTFOUND - no window found at given screen coordinates ALSO SEE whandle ------------------------------------------------------------------------ NAME windump DESCRIPTION 96 Dumps a screen window to the printer (PRN). SYNOPSIS #include "cxlprn.h" void windump(int srow,int scol,int erow,int ecol); INPUTS srow - start row scol - start column erow - end row ecol - end column ALSO SEE wdump EXAMPLE windump(0,0,9,79); /* prints top 10 lines of screen */ ------------------------------------------------------------------------ Multi-Field Input Functions Three functions are needed to process multi-field formatted input from windows: winpbeg(), winpdef(), and winpread(). The winpbeg() function marks the start of an input form. The winpdef() function defines an input field and is called for each input field to be defined. The winpread() function marks the end of the input form and processes all defined fields. The formatted input capabilities are much like those of the inputsf() and winputsf() functions. The major difference is that with the winpbeg()/winpdef()/winpread() combination, you can edit back and forth between fields before finally accepting the input. For every input field you want to define, you must call winpdef(). This will allocate memory to hold the input record information. The first two parameters, wrow and wcol, specify where in the active window the field will be loaded. The next parameter, str, is the address of the string buffer to receive the input data. The edited string will be terminated with a '\0'. This means if your format string is "AAAAA", your receiving field must be string[6] to hold the terminating '\0'. You can edit numeric information as well. There are 4 conversion functions to convert numbers to/from CXL fields: cvtic() - convert integer to CXL field string cvtci() - convert CXL field string to integer cvtfc() - convert real number to CXL field string cvtcf() - convert CXL field string to real number The next parameter, format, is the input field format string. It controls how each character is input and how large the input field will be. It consists of 1 or more format characters, and may have displayed text in between any of the format control characters. You may use spaces in between the format control characters for readability. Valid 97 format control characters are listed in the "Formatted Keyboard Input Functions" section. The case of the format control characters must be as shown. You can also specify a decimal point in the field. Format strings for winpdef() are just like those of inputsf() and winputsf() except there are no command toggles. The next parameter in the winpdef() function is fconv. These are similar to the command toggles of inputsf() and winputsf() except that the fconv character applies conversion to the whole field. Valid fconv characters are: 0 - apply no conversion 'L' - convert letters to lowercase 'M' - convert letters to mixed upper & lowercase 'P' - password field (do not echo characters) 'U' - convert letters to uppercase '9' - numeric field (right justify, space fill to the left of the decimal; and left justify, zero fill to the right of the decimal. After the fconv parameter comes the mode parameter. This parameter allows you to specify if the input field is going to create new data or update old data. If the mode parameter is 0, then the input field will be used for entering new data. If the mode parameter is nonzero, then the input field will be used to update the old data contained in the str parameter. If you specify 2 for mode, the cursor will appear at the end of the line and if an editing key is pressed first, the field will be used for updating, otherwise the field will be used to create new information. If you do choose to update, then the length of the input str will be adjusted to the field size either by truncation or padding with spaces. The next parameter in the winpdef() function is validate. This parameter is the address of an optional user validation/modification function. If no validation function is to be used, then specify NULL. Your user validation/modification function must be declared like: int func(char *str); where str is the address of the input field that will be passed to it. Once your user function has the address of the input field, you can validate and/or modify the input field. Your function can also display an error message, sound a bell, or just about anything. When your function is done, it must return 0 for no error, or the position in the field where the error occurred (starting with 1). The final parameter to winpdef(), help, is the address of the help category string to assign to this menu item. This is useful if you are using the context-sensitive help system and you want to assign a different help category to each field. If you do not need to use this feature, specify NULL for this parameter. The winpdef() function will return one of the following values: 98 W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates W_ALLOCERR - memory allocation error W_NOFRMBEG - no begin of form specified (winpbeg() not called) W_INVFORMT - invalid format string (syntax error) Once you have defined all input fields with winpdef(), you call winpread() to process them. The user is allowed to move around and edit all of the fields. The input fields are validated on the fly and after entering the last field. Valid editing keys are listed in Appendix E. After the winpread() function returns, all fields defined with winpdef() will be cleared. The receiving strings of all defined fields will now contain the data entered. If Escape checking was on and [Esc] was pressed, then all receiving strings will contain the values they held before winpread() was called and W_ESCPRESS will be returned. The general structure for defining input fields looks like: winpbeg(...); winpdef(...); winpdef(...); winpdef(...); winpread(); ------------------------------------------------------------------------ NAME winpbeg DESCRIPTION Marks the beginning of a data input form, and specifies text attributes to be used by the form. SYNOPSIS #include "cxlwin.h" int winpbeg(int fieldattr,int textattr); INPUTS fieldattr - field attribute textattr - text attribute RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window ALSO SEE winpdef winpread ------------------------------------------------------------------------ NAME 99 winpdef DESCRIPTION Defines a window input field. SYNOPSIS #include "cxlwin.h" int winpdef(int wrow,int wcol,char *str,char *format,int fconv, int mode,int (*validate) (char *),int help); INPUTS wrow - start of input, window's row coordinate wcol - start of input, window's column coordinate str - address of string buffer to receive input format - address of field format string. See Appendix D for valid format string characters. fconv - input field conversion character. Applies conversion to all characters in the input field. Can be one of the following: 0 - apply no conversion 'L' - convert letters to lowercase 'M' - convert letters to mixed case 'P' - password field (no echo) 'U' - convert letters to uppercase '9' - numeric field mode - field mode 0 - initial data entry 1 - update existing data 2 - conditional update validate - address of your user validation/modification function. If you do not wish to have a field validation function, then specify NULL. help - help category number to be associated with this input field. Specify 0 if no help category is to be assigned. RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOFRMBEG - no begin of form specified, see winpbeg() W_INVCOORD - invalid coordinates W_INVFORMT - invalid format string ALSO SEE winpbeg winpread ------------------------------------------------------------------------ NAME winpfba DESCRIPTION Assigns "before" and "after" function pointers to the input field just defined. The call to this function must appear immediately after the call to the winpdef() to which it relates. During user 100 input, when the user enters the field, the before function gets called. When the user leaves the validated field, the after function gets called. This powerful feature allows you to do some pretty advanced stuff with input fields, but must be used very carefully. SYNOPSIS #include "cxlwin.h" int winpfba(void (*before)(void),void (*after)(void)); INPUTS before - address of the before function. If you do not wish to define a before function, specify NULL. after - address of the after function. If you do not wish to define an after function, specify NULL. RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_NOFRMBEG - no begin of form defined. See winpbeg(). W_NOINPDEF - no input fields defined. See winpdef(). ALSO SEE winpbeg winpdef winpread ------------------------------------------------------------------------ NAME winpfcurr DESCRIPTION Returns the address of the current input field's record. After the call to this function, you may access any of the current input field's elements. See the definition of struct _field_t in the CXLWIN.H file for all of the elements you may use. Use caution when updating elements in the field's record. This function should only be called while the input form to which it relates is being processed. SYNOPSIS #include "cxlwin.h" struct _field_t *winpfcurr(void); RETURN VALUE The address of the current input field's record. You can access individual elements of the field's record by using this address and the C pointer operator "->". This function is a macro with no error checking, and will most likely return an invalid value if there isn't an active form. ALSO SEE winpbeg winpdef winpffind winpread EXAMPLE 101 printf("Length of current input field is: %d\n" ,winpfcurr()->lenfld); ------------------------------------------------------------------------ NAME winpffind DESCRIPTION Searches for a defined field whose window coordinates match the input coordinates, then returns the address of the field's record. After the call to this function, you may access any of the found input field's elements. See the definition of struct _field_t in the CXLWIN.H file for all of the elements you may use. Use caution when updating elements in the field's record. This function should only be called during the processing of the input form to which it relates. SYNOPSIS #include "cxlwin.h" struct _field_t *winpffind(int wrow,int wcol); INPUTS wrow - window row of field to search for wcol - window column of field to search for RETURN VALUE The address of the found field's record. You can access individual elements of the field's record by using this address and the C pointer operator "->". If an error occurred, then NULL will be returned and _winfo.errno will be set to one of the following values: W_NOACTIVE - no active window W_NOFRMDEF - no form defined. See winpbeg(). W_NOTFOUND - no defined field matches input window coordinates ALSO SEE winpbeg winpdef winpfcurr winpread ------------------------------------------------------------------------ NAME winpread DESCRIPTION Marks the end of the defined input form and initiates processing of the defined input fields. The user is allowed to edit back and forth between the defined fields until the last field is entered. Valid editing keys are listed in Appendix E. SYNOPSIS #include "cxlwin.h" int winpread(void); 102 RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_ESCPRESS - [Esc] key was pressed (only if Escape checking was on) W_NOINPDEF - no input fields defined ALSO SEE winpdef wsetesc ------------------------------------------------------------------------ NAME winputsf DESCRIPTION Inputs a formatted string from the keyboard. Typed-in characters will be echoed to the active window in the current text attribute. This function provides an extremely powerful method of accept single-line input from the user. You can limit input characters to certain characters of a type, such as numbers, insert strings in between typed in characters, create custom prompts, disable [Enter] until the field is filled, and more. Provides Escape checking. Updates cursor position. SYNOPSIS #include "cxlwin.h" int winputsf(char *str,char *fmt); INPUTS str - address of the allocated space to receive string fmt - address of the format string. See Appendix D for valid format string characters. RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_ESCPRESS - [Esc] key was pressed W_INVFORMT - invalid format string ALSO SEE wgetns wgets wscanf wsetesc wtextattr EXAMPLE char buf[10]; if(winputsf(buf,"'Enter phone nr: '!R--!'('!+!###!-!') '!+!###" "!-!'-'!+!####")) wprintf("Error: %s\n",werrmsg()); ------------------------------------------------------------------------ NAME winsline DESCRIPTION Inserts a blank line in the active window. Depending upon the input 103 scroll direction, lines will shift up or down to make room for the new line. SYNOPSIS #include "cxlwin.h" int winsline(int wrow,int direc); INPUTS wrow - window row to insert at direc - scroll direction: SUP - scroll up SDOWN - scroll down RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid window row ALSO SEE wdelline wscroll ------------------------------------------------------------------------ NAME wintodisk DESCRIPTION Copies a window of the screen to a disk file. SYNOPSIS #include "cxlvid.h" int wintodisk(int srow,int scol,int erow,int ecol,char *fname); INPUTS srow - start row of window scol - start column of window erow - end row of window ecol - end column of window fname - address of the string containing the filename of the file to write to RETURN VALUE Nonzero if an error occurred. ALSO SEE disktoscrn disktowin scrntodisk EXAMPLE wintodisk(10,10,20,40,"WINDOW.SAV"); ------------------------------------------------------------------------ NAME wisactiv 104 DESCRIPTION Determines if the specified window is active. SYNOPSIS #include "cxlwin.h" int wisactiv(WINDOW whandle); INPUTS whandle - the window handle of the window to check. RETURN VALUE Nonzero if specified window is active. ALSO SEE wactiv whandle ------------------------------------------------------------------------ Bar Menu Functions To use CXL's menuing system, you must be familiar with the process of defining menus. There are several functions associated with the defining of menus. These functions must appear in your source code in a certain order. Menu structures can be defined as simple as a one-level pop-up menu, or as complex as a multi-level pull-down menu system. The basic format of all menu structures is: <wmenubeg|wmenubegc> wmenuitem [wmenuitxt] [wmenuiba] [<wmenubeg|wmenubegc>...] [wmenuitem...] wmenuend wmenuget Either wmenubeg() or wmenubegc() is required to mark the start of a menu, wmenuitem() is required to define menu items, wmenuend() is required to mark the end of a menu, and wmenuget() initiates user processing of the entire menu structure. Notice that you can also define entire menus underneath any individual menu item. This allows you to easily create nested menus to aid in building complex pull-down and multi-layered menuing systems. There is no limit to how deep you can nest sub-menus, with the exception of available memory. When coding multi-level menu systems, it is a good idea to use indenting as shown above to help you distinguish which menu items and menu-ends go with which menu-begins. wmenuitxt() and wmenuiba() are optional functions. They allow you to add specific features to a menu item. If either of these 2 functions are used, they must immediately follow the call to wmenuitem() to which 105 they pertain. After you define the menu structure and call wmenuget(), the user is allowed to make a selection. The following editing keys may be used by the user when processing the menu: LeftArrow - moves selection bar to item left. RightArrow - moves selection bar to item right. UpArrow - moves selection bar to item upwards. DownArrow - moves selection bar to item downwards. If the current menu item has a pull-down menu attached, then it will be opened for processing. Enter - selects the item that the selection bar is on. If selected item has a sub-menu attached, then processing of that menu will begin. Home - moves selection bar to upper-leftmost item. End - moves selection bar to lower-rightmost item. Esc - if Escape checking is on, and your are in the root menu, pressing this cancels input and returns a -1. If inside a sub-menu, then you will just back up to the previous menu. You can also quick-select a menu item by pressing its highlighted selection character, unless this feature is disabled. CXL's menuing system also includes built-in mouse support. If you want to use it, you need to call msinit() somewhere near the beginning of the program. This will set the mouse support level to MS_KEYS, which allows the mouse to emulate cursor keys. If you would like a point-and-shoot selection capability where the user moves the mouse cursor around then presses the button to select, you must set the mouse support level to MS_CURS or MS_FULL via mssupport(). In either method of mouse support, the left mouse button is equivalent to the [Enter] key, and the right mouse button is equivalent to the [Esc] key. Each menu item can have a function and/or sub-menu attached to it. When the user selects the menu item, wmenuget() will first check for an attached sub-menu. If one exists, it will be processed. Then wmenuget() will check for a defined select function. If one exists, then wmenuget() will call it. This gives you two ways to handle a user selection. The first, as you've seen, is to have a function attached to the menu item. For example, if the menu item is "(A)dd Record" and it has a select function called add_record(), then it will be called upon selecting that menu item. The other way to handle a user selection is by using a switch/case to test the return value from wmenuget(). This will only work properly on single-level menus, but sometimes gives you more flexibility. ------------------------------------------------------------------------ NAME wmenubeg 106 DESCRIPTION Starts a menu/sub-menu definition and describes the window which the menu will reside in. This does not actually open any windows or menus, just defines them. This must be used in conjuction with wmenuitem() and wmenuend(). This is one of the 4 functions that are required to process a menu. SYNOPSIS #include "cxlwin.h" int wmenubeg(int srow,int scol,int erow,int ecol,int btype, int battr,int wattr,void (*open)(void)); INPUTS srow - screen start row of where menu's window will open scol - screen start column of where menu's window will open erow - screen end row of where menu's window will open ecol - screen end column of where menu's window will open btype - border type. Can be one of the following: 0 - single line 1 - double line 2 - single horizontal, double vertical line 3 - double horizontal, single vertical line 4 - thick line 5 - no border battr - attribute to be used for the menu window's border. If btype==5, then this value will be ignored. wattr - attribute to be used for the menu's window. open - address of the function to call upon opening of the menu's window. If you want to add a title, shadow, etc. to the menu's window after it opens, this lets you specify which function to call to perform these tasks. Specify NULL if you don't want to use this feature. RETURN VALUE W_NOERROR - no error W_NOITMDEF - no menu items defined W_ALLOCERR - memory allocation error ALSO SEE wmenubegc wmenuitem wmenuend wmenuget EXAMPLE wmenubeg(2,10,9,18,0,YELLOW,_BLUE,NULL); ------------------------------------------------------------------------ NAME wmenubegc DESCRIPTION Starts a menu/sub-menu definition. This is used in place of wmenubeg(). This function differs from wmenubeg() in that when the user processes the defined menu, the menu will assume whatever the active window is at the time. 107 SYNOPSIS #include "cxlwin.h" int wmenubegc(void); RETURN VALUE W_NOERROR - no error W_NOITMDEF - no menu items defined W_ALLOCERR - memory allocation error ALSO SEE wmenubeg wmenuitem wmenuend wmenuget ------------------------------------------------------------------------ NAME wmenuend DESCRIPTION Ends a menu/sub-menu definition and defines specific features/attributes of that menu. This is one of the 4 functions that are required to process a menu. SYNOPSIS #include "cxlwin.h" int wmenuend(int taginit,int menutype,int barwidth,int textpos, int textattr,int scharattr,int noselattr,int barattr); INPUTS taginit - tag ID of the item that the selection bar will start at. If an invalid tag ID is given, then the selection bar will start at the upper-leftmost item. menutype - a mask which describes how the menu will act. Two or more menutypes can be combined using the bitwise OR operator '|'. For example, if the menu you are defining is to be a pull-down menu, and you want to disable quick selection, then you would specify M_PD|M_NOQS. Valid menutypes are: M_HORZ - horizontal menu M_VERT - vertical menu M_OMNI - omnidirectional menu M_PD - pull-down menu M_SAVE - save last bar position M_NOQS - disable quick selection barwidth - width of the selection bar. If zero is given, then the selection bar will conform to the width of each menu item. If a number greater than the width of the window is given, then the barwidth will be adjusted to its width. textpos - offset position from the start of the selection bar that the menu item text will start. If barwidth==0, then textpos is ignored. textattr - attribute to be used for menu text scharattr - attribute to be used for the quick selection character noselattr - attribute to be used for nonselectable text 108 barattr - attribute to be used for the selection bar RETURN VALUE W_NOERROR - no error W_NOITMDEF - no menu items defined ALSO SEE wmenubeg wmenubegc wmenuget wmenuitem EXAMPLE wmenuend('F',M_VERT,20,2,YELLOW|_BLUE,LCYAN|_BLUE,LGREY|_BLUE ,BLUE|_LGREY); ------------------------------------------------------------------------ NAME wmenuget DESCRIPTION Processes the defined menu structure. The user is allowed to move a selection bar around to the various menu items. If mouse support is on, then the user can use the mouse for selecting as well. If sub-menus exists, then the user can select those also. Escape checking is provided for when the user is in the root menu, however if the user is in a sub-menu, pressing [Esc] will always return to the next level up. This is one of the 4 functions that are required to process a menu. SYNOPSIS #include "cxlwin.h" int wmenuget(void); RETURN VALUE The tag ID of the menu item that was selected in the root menu. If an error occurred, then -1 will be returned and the global variable _winfo.errno will be set to one of the following: W_NOMNUDEF - no menu defined W_NOMNUEND - no end of menu specified. See wmenuend(). W_ESCPRESS - the [Esc] key was pressed from the root menu W_ALLOCERR - memory allocation error W_INVCOORD - invalid coordinates W_INVBTYPE - invalid box type ALSO SEE wmenubeg wmenubegc wmenuend wmenuitem wsetesc ------------------------------------------------------------------------ NAME wmenuiba DESCRIPTION Assigns "before" and "after" function pointers to the menu item just defined. The call to this function must appear immediately after 109 the call to the wmenuitem() to which it relates. During the processing of the menu, when the user moves to the item, the before function gets called. When the user leaves the item, the after function gets called. This powerful feature allows you to do some advanced stuff with menus, but must be used very carefully. One possible use of wmenuiba() is to define a before function that opens a window and writes some text in it, and an after function which closes that window. When the user moved to that menu item, the window would open up and display text, then when the user left that menu item, the window would automatically close. SYNOPSIS #include "cxlwin.h" int wmenuiba(void (*before)(void),void (*after)(void)); INPUTS before - address of the before function. If you do not wish to define a before function, specify NULL. after - address of the after function. If you do not wish to define an after function, specify NULL. RETURN VALUE W_NOERROR - no error W_NOITMDEF - no menu items defined. See wmenuitem(). ALSO SEE wmenubeg wmenuend wmenuget wmenuitem wmenuitxt ------------------------------------------------------------------------ NAME wmenuicurr DESCRIPTION Returns the address of the current menu item's record. After this call, you may access any of the item's elements. This would most likely be used in a function called by a menu item. See the struct _item_t definition in the CXLWIN.H file for all the elements you may use. SYNOPSIS #include "cxlwin.h" struct _item_t *wmenuicurr(void); RETURN VALUE The address of the current menu item's record. ALSO SEE wmenubeg wmenuend wmenuget wmenuifind wmenuitem wmenumcurr EXAMPLE printf("The current menu item's tagid = %d\n",wmenuicurr()->tagid); ------------------------------------------------------------------------ 110 NAME wmenuifind DESCRIPTION Searches the menu tree structure for the record of the menu item matching the input tag identifier, then returns the found record's address. After the call to this function, you may access any of the found menu item's elements. See the definition of struct _item_t in the CXLWIN.H file for all of the elements you may use. Use caution when updating elements in the menu item's record. This function should only be called during the processing of the menu to which it relates. SYNOPSIS #include "cxlwin.h" struct _item_t *wmenuifind(int tagid); INPUTS tagid - the tag identifier of the menu item to find RETURN VALUE The address of the found menu item's record. You can access individual elements of the menu item's record by using this address and the C pointer operator "->". If an error occurred, then NULL will be returned and _winfo.errno will be set to one of the following values: W_NOMNUDEF - no menu is defined. See wmenubeg(). W_NOTFOUND - input tag identifier not found ALSO SEE wmenubeg wmenuend wmenuget wmenuicurr wmenuitem ------------------------------------------------------------------------ NAME wmenuitem DESCRIPTION Defines a menu item. This is one of the 4 functions that are required to process a menu. SYNOPSIS #include "cxlwin.h" int wmenuitem(int wrow,int wcol,char *str,int schar,int tagid, int fmask,void (*select)(void),unsigned hotkey, int help); INPUTS wrow - window row wcol - window column str - address of menu item string schar - quick selection character tagid - unique tag identifier of this particular menu item. This is the value that wmenuget() returns upon its selection. 111 fmask - feature mask. Allows you to define one or more additional features for this menu item. Valid features are: M_HASPD - has a pull-down menu attached M_NOSEL - menu item is not selectable M_CLOSE - close this menu when item is selected M_CLALL - close all menus when item is selected More than one feature can be specified by using the C bitwise OR operator '|'. For example, if this item has a pull-down menu attached and it is not selectable, you would specify (M_HASPD|M_NOSEL). Specify 0 if you don't want to define an fmask for this item. select - address of the function to call upon selection of this menu item. Specify NULL if you don't want to define a select function. hotkey - keycode of the key, which when pressed, will select this menu item's function from anywhere within the menu structure. This allows the user to call this menu item's select function even if not currently processing its menu. See Appendix B for a list of keycodes that you can use. Specify 0 if you don't want to define a hotkey. help - help category number to be associated with this item. Specify 0 is you don't want to define a help category for this item. RETURN VALUE W_NOERROR - no error W_NOMNUBEG - no begin of menu specified. See wmenubeg(). W_ALLOCERR - memory allocation error ALSO SEE wmenubeg wmenubegc wmenuend wmenuget wmenuicurr wmenuitxt EXAMPLE wmenuitem(0,0,"Load F3",'L',1,M_CLOSE,load_file,0x3d00,0); ------------------------------------------------------------------------ NAME wmenuitxt DESCRIPTION Adds a text description to a menu item. You can use this function to create Lotus-style menus where the text descriptions are displayed underneath the menu and change each time the user moves to a new menu item. SYNOPSIS #include "cxlwin.h" int wmenuitxt(int wrow,int wcol,int attr,char *str); INPUTS wrow - window row wcol - window column attr - text attribute 112 str - address of description string RETURN VALUE W_NOERROR - no error W_NOITMDEF - no menu items defined ALSO SEE wmenuiba wmenuitem EXAMPLE wmenuitxt(1,0,LCYAN|_BLUE,"Quit program and return to DOS"); ------------------------------------------------------------------------ NAME wmenumcurr DESCRIPTION Returns the address of the currently active menu's record. After this call, you may access any of the menu's elements. See the definition of struct _menu_t in the CXLWIN.H file for all of the elements you may use. Use caution when updating elements in the menu's record. This function should only be called while the menu to which it relates is being processed. SYNOPSIS #include "cxlwin.h" struct _menu_t *wmenumcurr(void); RETURN VALUE The address of the current menu's record. After you get this address, you can access the menu's elements via the C pointer operator "->". There is no error return value - if you call this function while not processing a menu, then you will more than likely get an invalid address. ALSO SEE wmenubeg wmenuend wmenuget wmenuicurr wmenuitem ------------------------------------------------------------------------ NAME wmessage DESCRIPTION Displays text on the top or bottom border of the active window. SYNOPSIS #include "cxlwin.h" int wmessage(char *str,int border,int leftofs,int attr); INPUTS str - address of message string border - 0 = top border, 1 = bottom border 113 leftofs - offset from left border to display message at attr - attribute of message text RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_STRLONG - string could not fit in window W_NOBORDER - window has no border ALSO SEE wtitle EXAMPLE wmessage("[ F1=Help ]",1,2,YELLOW|_BLACK); ------------------------------------------------------------------------ NAME wmove DESCRIPTION Moves the active window to a new location on the screen. SYNOPSIS #include "cxlwin.h" int wmove(int nsrow,int nscol); INPUTS nsrow - new starting row of window nscol - new starting column of window RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window ALSO SEE wcopy wsize ------------------------------------------------------------------------ NAME wopen DESCRIPTION Opens a screen window and makes it active. The cursor location will be initialized to window row 0, column 0. The text attribute will be initialized to the same attribute as the window. You can open as many windows as memory permits. SYNOPSIS #include "cxlwin.h" WINDOW wopen(int srow,int scol,int erow,int ecol,int btype, int battr,int wattr); 114 INPUTS srow - starting row scol - starting column erow - ending row ecol - ending column btype - box type. Can be one of the following: 0 - single line border 1 - double line border 2 - single horz, double vert line border 3 - double horz, single vert line border 4 - thick line border 5 - no border (uses spaces for border chars). A borderless window has a greater effective window area than a window with a border. battr - attribute of window's border. wattr - attribute of window (and initially the text) RETURN VALUE The window handle of the new window or a zero if an error occurred. If error, the global variable _winfo.errno will be set to one of the following: W_ALLOCERR - memory allocation error W_INVCOORD - invalid coordinates W_INVBTYPE - invalid box type ALSO SEE videoinit wactiv wclose wcloseall wfillch EXAMPLE wopen(10,10,20,40,0,LCYAN|_BLUE,LGREEN|_BLUE); ------------------------------------------------------------------------ NAME wperror DESCRIPTION Opens an error window, displays an error message, sounds a beep, waits for a keypress, then returns to caller. The error window is opened in the general vicinity of the cursor position. SYNOPSIS #include "cxlwin.h" int wperror(char *message); INPUTS message - address of the string containing the error message RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error W_STRLONG - error message string too long ALSO SEE 115 werrmsg EXAMPLE wperror("Field cannot be blank!"); ------------------------------------------------------------------------ NAME wpgotoxy DESCRIPTION Sets cursor coordinates within the active window. If cursor coordinates are out of the window, wpgotoxy() will try to wrap them around to fit in the window. SYNOPSIS #include "cxlwin.h" int wpgotoxy(int wrow,int wcol); INPUTS wrow - window row (Y coordinate) wcol - window column (X coordinate) RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates ALSO SEE wgotoxy wreadcur ------------------------------------------------------------------------ NAME wpickfile DESCRIPTION This function will open up a window and display as many file/directory names in it as it can. The user can use a selection bar to move through the file/directory names and select one. If all of the file/directory names cannot fit in the window, scrolling and paging is allowed. If the user selects a directory, wpickfile() will change to that directory and display the list of files/directories in it. After the selection is made, wpickfile() will return the complete path name of the selected file. SYNOPSIS #include "cxlwin.h" char *wpickfile(int srow,int scol,int erow,int ecol,int btype, int bordattr,int winattr,int barattr,int title, char *filespec,void (*open)(void)); INPUTS srow - start row of pick window 116 scol - start column of pick window erow - end row of pick window ecol - end column of pick window. If ecol==-1, then the window's width will conform to that of the longest matching filename. btype - window box type (0-5) bordattr - border attribute winattr - window attribute barattr - selection bar attribute title - display filespec title on upper border? (0=no, 1=yes) filespec - match filespec (ie. "*.*") open - address of the function to call upon each opening of the file pick window. If you do not need to use this feature, specify NULL. RETURN VALUE The address of the static string containing the full drive:path\filename string of the selected file. If an error occurred, NULL will be returned and _winfo.errno will be set to one of the following: W_ESCPRESS - the [Esc] key was pressed W_ALLOCERR - memory allocation error W_DOSERROR - DOS error (ie. invalid directory) W_INVCOORD - invalid window coordinates W_INVBTYPE - invalid box type W_STRLONG - window not wide enough to hold largest file name W_NOMATCH - no files matched input filespec ALSO SEE wpickstr wsetesc EXAMPLE char *fname; fname=wpickfile(10,10,20,65,0,LCYAN|_BLUE,CYAN|_BLUE,BLUE|_LGREY,1 ,"*.*",NULL); printf("You selected: %s\n",fname); ------------------------------------------------------------------------ NAME wpickstr DESCRIPTION This function will open up a window and display as many of the input strings in it as it can. The user can use a selection bar to move through the strings and select one. If all of the strings cannot fit in the window, scrolling and paging is allowed. After the selection is made, wpickstr() will return the array subsript of the string that was selected. SYNOPSIS #include "cxlwin.h" int wpickstr(int srow,int scol,int erow,int ecol,int btype, int bordattr,int winattr,int barattr,char *strarr[], 117 void (*open)(void)); INPUTS srow - start row of pick window scol - start column of pick window erow - end row of pick window ecol - end column of pick window. If ecol==-1, then the window's width will conform to that of the longest string in the input array. btype - window box type (0-5) bordattr - border attribute winattr - window attribute barattr - selection bar attribute strarr - address of array of char pointers (strings) to select from. The last pointer in the array MUST be NULL! open - address of the function to call upon each opening of the string pick window. If you do not need to use this feature, specify NULL. RETURN VALUE The array subscript of the selected string. If an error occurred, then -1 will be returned and _winfo.errno will be set to one of the following: W_ESCPRESS - the [Esc] key was pressed W_INVCOORD - invalid window coordinates W_INVBTYPE - invalid box type W_STRLONG - window not wide enough to hold largest file name ALSO SEE wpickfile wselstr wsetesc EXAMPLE int i; char *days[]= { "Sunday","Monday","Tuesday","Wednesday","Thursday", "Friday","Saturday",NULL }; i=wpickstr(10,10,14,-1,0,YELLOW,LCYAN|_BLUE,BLUE|_LGREY,days,NULL); if(i!=-1) wprintf("You selected %s\n",days[i]); ------------------------------------------------------------------------ NAME wprintc DESCRIPTION Displays a character in the active window. Control characters are not recognized. Cursor position is not updated. SYNOPSIS #include "cxlwin.h" int wprintc(int row,int col,int attr,int ch); INPUTS row - window row to display character at col - window column to display character at 118 attr - text attribute for character ch - character RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates ALSO SEE wprints wputc EXAMPLE wprintc(5,5,BLINK|LRED|_GREEN,'X'); ------------------------------------------------------------------------ NAME wprintf DESCRIPTION Displays a formatted string to the active window at the current cursor position. Works like the standard printf() function does. Recognizes control characters. Characters will be displayed in the attribute set by the wtextattr() function. Updates cursor position. Also recognizes CXL Escape sequences. See Appendix C for a list of valid Escape codes. SYNOPSIS #include "cxlwin.h" int wprintf(const char *format,...); INPUTS format - address of the format string. Refer to the your compiler's run-time library reference manual for information on valid format characters. ... - any additional arguments RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wputc wputns wputs wtabwidth wtextattr EXAMPLE int i=32767; double d=3.14159; char ch='X',*str="Hello, world"; wprintf("i = %d, d = %f, ch = %c, str = %s\n",i,d,ch,str); ------------------------------------------------------------------------ NAME wprints 119 DESCRIPTION Displays a string in the active window. Control characters are not recognized. Cursor position is not updated. SYNOPSIS #include "cxlwin.h" int wprints(int wrow,int wcol,int attr,char *str); INPUTS wrow - window row to display string at wcol - window column to display string at attr - text attribute for displayed characters str - address of string RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates W_STRLONG - string too long for window ALSO SEE wcenters wprintsf wputs wrjusts wwprints EXAMPLE wprints(10,15,BLINK|YELLOW|_BROWN,"Hello, world"); ------------------------------------------------------------------------ NAME wprintsf DESCRIPTION Displays a string to active window using a CXL format string. If a character in a string doesn't match its format control character, it will be displayed as a '?'. Control characters are not recognized. Cursor position is not updated. SYNOPSIS #include "cxlwin.h" int wprintsf(int wrow,int wcol,int attr,char *format,char *str); INPUTS wrow - window row wcol - window column attr - text attribute format - address of format string. Valid format string characters are listed in Appendix D. str - address of the string to display. RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVFORMT - invalid format string W_STRLONG - there were more characters in the display string than 120 the format string would display. ALSO SEE wprints EXAMPLE char str1[]="5125900460",str2[]="(512) 590-2910"; wprintsf(3,5,LGREEN|_GREEN,"'('###') '###'-'####",str1); wprintsf(4,5,LGREEN|_GREEN,"##############",str2); ------------------------------------------------------------------------ NAME wputc DESCRIPTION Displays a character in the active window at current cursor position using current text attribute. Recognizes control characters. Updates cursor position. SYNOPSIS #include "cxlwin.h" int wputc(int ch); INPUTS ch - the character to be displayed RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wdupc wprintc wprintf wtabwidth wtextattr ------------------------------------------------------------------------ NAME wputns DESCRIPTION Displays a string in the active window at the current cursor location using current text attribute. The input width will determine how many characters are actually displayed. Padding with spaces or truncating of output will be used where neccessary. Recognizes control characters. Updates cursor position. SYNOPSIS #include "cxlwin.h" int wputns(char *str,int width); INPUTS str - address of the string to print width - width to display output string at 121 RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wprintf wputs wtextattr EXAMPLE wputns("Hello, world",5); ------------------------------------------------------------------------ NAME wputs DESCRIPTION Displays a string in the active window at the current cursor position using current text attribute. Recognizes control characters. Updates cursor position. Also recognizes CXL Escape sequences. See Appendix C for a list of valid Escape codes. SYNOPSIS #include "cxlwin.h" int wputs(char *str); INPUTS str - the address of the string to display RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wprintf wprints wputns wputsw wtabwidth wtextattr EXAMPLE wputs("\t\033LHello, \033Lworld!\n\n"); ------------------------------------------------------------------------ NAME wputsw DESCRIPTION Displays a string in active window at the current cursor position. Words will be wrapped around to the next line if necessary. Characters are displayed in the window's current text attribute. Recognizes control characters. Updates cursor position. Also recognizes CXL Escape sequences. See Appendix C for a list of valid Escape codes. SYNOPSIS #include "cxlwin.h" int wputsw(char *str); 122 INPUTS str - the address of the string to display RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wprintf wputs wtextattr EXAMPLE wputsw("This is a very long string that will be wrapped around to " "the next line."); ------------------------------------------------------------------------ NAME wreadcur DESCRIPTION Reads the current cursor coordinates of the active window. SYNOPSIS #include "cxlwin.h" int wreadcur(int *wrow,int *wcol); INPUTS wrow - address of integer to receive current window row wcol - address of integer to receive current window column RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wgotoxy EXAMPLE int wrow,wcol; wreadcur(&wrow,&wcol); ------------------------------------------------------------------------ NAME wrestore DESCRIPTION Restores a previously saved region of the screen screen and frees the memory allocated by wsave(). SYNOPSIS #include "cxlwin.h" void wrestore(int *wbuf); 123 INPUTS wbuf - address of previously wsave()d window. ALSO SEE srestore wsave ------------------------------------------------------------------------ NAME wrjusts DESCRIPTION Displays a string right justified to specified column in the active window. Does not recognize control characters. Does not update cursor position. SYNOPSIS #include "cxlwin.h" int wrjusts(int wrow,int wjcol,int attr,char *str); INPUTS wrow - window row to display string at wjcol - window column that string will right justify to attr - text attribute for displayed characters str - address of string to display RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates W_STRLONG - string too long to fit in window at specified right justification column. ALSO SEE wcenters wprints ------------------------------------------------------------------------ NAME wsave DESCRIPTION Saves a region of the screen. SYNOPSIS #include "cxlwin.h" int *wsave(int srow,int scol,int erow,int ecol); INPUTS srow - start row scol - start column erow - end row ecol - end column 124 RETURN VALUE Address of newly created window buffer or NULL if a memory allocation error occurred. ALSO SEE ssave videoinit wintodisk wrestore EXAMPLE int *wbuf; if((wbuf=wsave(10,10,20,40))==NULL) printf("Memory allocation error\n"); ------------------------------------------------------------------------ NAME wscanf DESCRIPTION Inputs a formatted string from keyboard. Entered characters will echo to the active window in the attribute set by the wtextattr() function. Cursor position will be updated. Works like the standard C library function scanf() does. This function is only supported by the Turbo C version of CXL. SYNOPSIS #include "cxlwin.h" int wscanf(const char *format,...); INPUTS format - format string. Refer to the section on scanf() in Turbo C's run-time library reference manual. ... - any additional arguments RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wgetc wgetns wgets winputsf wtextattr ------------------------------------------------------------------------ NAME wscroll DESCRIPTION Scrolls text lines within the active window, up or down. SYNOPSIS #include "cxlwin.h" int wscroll(int count,int direc); INPUTS count - number of lines to scroll 125 direc - scroll direction: SUP - scroll up SDOWN - scroll down RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wdelline winsline wscrollbox ------------------------------------------------------------------------ NAME wscrollbox DESCRIPTION Scrolls a region of the active window up or down. SYNOPSIS #include "cxlwin.h" int wscrollbox(int wsrow,int wscol,int werow,int wecol,int count, int direc); INPUTS wsrow - window start row wscol - window start column werow - window end row wecol - window end column count - number of lines to scroll direc - direction of scroll: SUP - scroll up SDOWN - scroll down RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wdelline winsline wscroll ------------------------------------------------------------------------ NAME wselstr DESCRIPTION Allows user to select one string from an array of strings via an in-place "menu". Provides Escape checking. SYNOPSIS #include "cxlwin.h" int wselstr(int wrow,int wcol,int attr,char *strarr[]); 126 INPUTS wrow - window row to display selections at wcol - window column to display selections at attr - attribute for selection text strarr - the array of string (char *) pointers which to pick from. The last pointer in the array MUST be NULL! RETURN VALUE The array subscript of the string which was selected. If an error occurred, then -1 will be returned and _winfo.errno will be set to one of the following: W_NOACTIVE - no active window W_ESCPRESS - [Esc] key was pressed (if Escape checking was on) ALSO SEE wpickstr wsetesc EXAMPLE int i; char *prn_ports[]= { "PRN","LPT1","LPT2","COM1","COM2",NULL }; wprints(0,0,LCYAN|_BLUE,"Select printer:"); i=wselstr(0,16,LMAGENTA|_BLUE,prn_ports); if(i!=-1) wprintf("You selected %s\n",prn_ports[i]); ------------------------------------------------------------------------ NAME wsetesc DESCRIPTION Sets the Escape checking status for window keyboard input functions that utilize Escape checking. By default, Escape checking is on. SYNOPSIS #include "cxlwin.h" void wsetesc(int option); INPUTS option - 0 = turn Escape checking off, 1 = turn Escape checking on ALSO SEE wgetchf wgetns winpread winputsf wmenuget wpickfile wpickstr ------------------------------------------------------------------------ NAME wshadoff DESCRIPTION Removes the shadow from the active window, if one exists. This function is only needed when you want to prematurely remove the active window's shadow. The wclose() function automatically calls wshadoff() when it closes a window. 127 SYNOPSIS #include "cxlwin.h" int wshadoff(void); RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE wclose wshadow ------------------------------------------------------------------------ NAME wshadow DESCRIPTION Gives the active window a shadow. The shadow will be cast to the right of the window and will be translucent (the characters underneath the shadow will show through in the given attribute). SYNOPSIS #include "cxlwin.h" int wshadow(int attr); INPUTS attr - attribute to use for the shadow and the characters underneath it. The most realistic looking shadow will be achieved using DGREY|_BLACK, but depending upon the contrast setting on your monitor, underlying characters may not be visible. Several commercial programs use a shadow attribute of LGREY|_BLACK for this reason. RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_ALLOCERR - memory allocation error ALSO SEE wshadoff EXAMPLE wshadow(DGREY|_BLACK); ------------------------------------------------------------------------ NAME wsize DESCRIPTION Adjusts the size of the active window by changing the screen coordinates of its lower-right corner. SYNOPSIS 128 #include "cxlwin.h" int wsize(int nerow,int necol); INPUTS nerow - new end row of window necol - new end column of window RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates ALSO SEE wcopy wmove ------------------------------------------------------------------------ NAME wtabwidth DESCRIPTION Modifies the tab width to be used when displaying tabs in the active window via the window TTY output functions. The default tab width is 8. SYNOPSIS #include "cxlwin.h" void wtabwidth(int tabwidth); INPUTS tabwidth - the new tab width EXAMPLE wputs("\n\tHello, world"); wtabwidth(4); wputs("\n\tHello, world"); ------------------------------------------------------------------------ NAME wtextattr DESCRIPTION Sets the current text attribute for the active window. The current text attribute is used by the window TTY output functions for displaying text inside the active window. SYNOPSIS #include "cxlwin.h" int wtextattr(int attr); INPUTS attr - the new text attribute 129 RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window ALSO SEE attrib wchgattr EXAMPLE wtextattr(LCYAN|_GREEN|BLINK); wputs("Hello, world\n"); ------------------------------------------------------------------------ NAME wtitle DESCRIPTION Gives active window a title and displays title on top border line of window. If active window has no border, then the window's record will be updated, but no title will be visible. SYNOPSIS #include "cxlwin.h" int wtitle(char *str,int tpos,int tattr); INPUTS str - address of title string or NULL to delete title tpos - title position. If str==NULL then tpos is ignored. Valid tpos values are: TLEFT - left justified TCENTER - centered TRIGHT - right justified tattr - attribute of window's title RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_ALLOCERR - memory allocation error ALSO SEE wmessage EXAMPLE wtitle("[ My Window ]",TCENTER,YELLOW|_BROWN); ------------------------------------------------------------------------ NAME wunhide DESCRIPTION Unhides a previously hidden window. The unhidden window becomes the active window. 130 SYNOPSIS #include "cxlwin.h" int wunhide(WINDOW whandle); INPUTS whandle - the handle of the window to unhide. If you want to unhide the most recently hidden window, then specify 0. RETURN VALUE W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOTFOUND - window handle not found W_NOHIDDEN - no hidden windows W_NOTHIDD - window not hidden ALSO SEE whide ------------------------------------------------------------------------ NAME wvline DESCRIPTION "Draws" a vertical text line in the active window using characters defined by the given box type. If the vertical line crosses a horizontal line of the same box type, an appropriate intersection or corner will be displayed. SYNOPSIS #include "cxlwin.h" int wvline(int wsrow,int wscol,int count,int btype,int attr); INPUTS wsrow - window start row wscol - window start column count - number of line characters to display btype - box type. Can be one of the following: 0 - single line 1 - double line 2 - single horz, double vert line 3 - double horz, single vert line 4 - thick line 5 - uses spaces for line characters attr - attribute to use for text line RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - entire text line could not fit in window W_INVBTYPE - invalid box type ALSO SEE whline 131 ------------------------------------------------------------------------ NAME wwprints DESCRIPTION Prints a string to the specified window. The specified window can be active, hidden, or blocked. Control characters are not recognized. Cursor position is not updated. SYNOPSIS #include "cxlwin.h" int wwprints(WINDOW whandle,int wrow,int wcol,int attr,char *str); INPUTS whandle - handle of window to display to wrow - window row to write string to wcol - window column to write string to attr - text attribute for written characters str - address of string to display RETURN VALUE W_NOERROR - no error W_NOACTIVE - no active window W_NOTFOUND - window handle not found W_INVCOORD - invalid window coordinates W_STRLONG - string too long (not all of string was displayed) ALSO SEE wprints 132 Appendix A - Text Attribute Identifiers Foreground Colors Background Colors Identifier Color Identifier Color ---------- ----- ---------- ----- BLACK - black _BLACK - black BLUE - blue _BLUE - blue GREEN - green _GREEN - green CYAN - cyan _CYAN - cyan RED - red _RED - red MAGENTA - magenta _MAGENTA - magenta BROWN - brown _BROWN - brown LGREY - light grey _LGREY - light grey DGREY - dark grey LBLUE - light blue LGREEN - light green LCYAN - light cyan LRED - light red LMAGENTA - light magenta YELLOW - yellow WHITE - white BLINK - blinking foreground Example Usage: BLINK|WHITE|_RED - blinking white on red YELLOW|_BLUE - yellow on blue LMAGENTA - light magenta on black _BLUE - black on blue 133 Appendix B - Keycode Table Key Norm Shift Ctrl Alt ---- ---- ----- ---- --- A 1E61 1E41 1E01 1E00 B 3062 3042 3002 3000 C 2E63 2E42 2E03 2E00 D 2064 2044 2004 2000 E 1265 1245 1205 1200 F 2166 2146 2106 2100 G 2267 2247 2207 2200 H 2368 2348 2308 2300 I 1769 1749 1709 1700 J 246A 244A 240A 2400 K 256B 254B 250B 2500 L 266C 264C 260C 2600 M 326D 324D 320D 3200 N 316E 314E 310E 3100 O 186F 184F 180F 1800 P 1970 1950 1910 1900 Q 1071 1051 1011 1000 R 1372 1352 1312 1300 S 1F73 1F53 1F13 1F00 T 1474 1454 1414 1400 U 1675 1655 1615 1600 V 2F76 2F56 2F16 2F00 W 1177 1157 1117 1100 X 2D78 2D58 2D18 2D00 Y 1579 1559 1519 1500 Z 2C7A 2C5A 2C1A 2C00 1 0231 0221 N/A 7800 2 0332 0340 0300 7900 3 0433 0423 N/A 7A00 4 0534 0524 N/A 7B00 5 0635 0625 N/A 7C00 6 0736 075E 071E 7D00 7 0837 0826 N/A 7E00 8 0938 092A N/A 7F00 9 0A39 0A28 N/A 8000 0 0B30 0B29 N/A 8100 , 332C 333C N/A N/A . 342E 343E N/A N/A / 352F 353F N/A N/A ; 273B 273A N/A N/A ' 2827 2822 N/A N/A [ 1A5B 1A7B 1A1B N/A ] 1B5D 1B7D 1B1D N/A ` 2960 297E N/A N/A - 0C2D 0C5F 0C1F 8200 = 0D3D 0D2B N/A 8300 \ 2B5C 2B7C 2B1C N/A 134 Key Norm Shift Ctrl Alt ---- ---- ----- ---- --- F1 3B00 5400 5E00 6800 F2 3C00 5500 5F00 6900 F3 3D00 5600 6000 6A00 F4 3E00 5700 6100 6B00 F5 3F00 5800 6200 6C00 F6 4000 5900 6300 6D00 F7 4100 5A00 6400 6E00 F8 4200 5B00 6500 6F00 F9 4300 5C00 6600 7000 F10 4400 5D00 6700 7100 Enter 1C0D 1C0D 1C0A N/A Ins 5200 5230 N/A N/A Del 5300 532E N/A N/A Esc 011B 011B 011B N/A Home 4700 4737 7700 N/A End 4F00 4F31 7500 N/A PgUp 4900 4939 8400 N/A PgDn 5100 5133 7600 N/A <Tab> 0F09 0F00 N/A N/A <BackSpace> 0E08 0E08 0E7F N/A <LeftArrow> 4B00 4B34 7300 N/A <RightArrow> 4D00 4D36 7400 N/A <UpArrow> 4800 4838 N/A N/A <DownArrow> 5000 5032 N/A N/A <Keypad 5> N/A 4C35 N/A N/A <Grey *> 372A N/A 7200 N/A <Grey -> 4A2D 4A2D N/A N/A <Grey +> 4E2B 4E2B N/A N/A 135 Appendix C - Window Output Escape Codes Escape Code Function ----------- -------- + - increase text attribute - - decrease text attribute A? - set text attribute to ? F? - set foreground text attribute to ? B? - set background text attribute to ? I - toggle intensity L - toggle blink X - reverse text attribute R? - set window row coordinate to ? C? - set window column coordinate to ? E? - erase ?: W - entire window L - to end-of-line S - to end-of-window D?? - display ? character ? times Window output Escape codes are only available in the window TTY output string functions. Valid functions are wprintf(), wputs(), wputsw(), and others. Also, the text inside help files can contain Escape codes (excluding cross-reference items). The Escape code parameters MUST be character (byte) size. Parameters should be input as binary. For example, 5 would be '\005'. If you are using them from inside a wprintf() format string, you can use the '%c' format specifier to supply the parameter from the list of variables. Example Usage: wprintf("\033A%cNormal \033IBright\033I \033LBlink\033L" " \033XReverse\033X\n",CYAN|_BLUE); wprintf("\033R%c\033C%cRow %d, Col %d\n",3,5,3,5); wputs("\033DA\014 = 'A' 12 times\n"); 136 Appendix D - Format Control Characters FCC Description --- ----------- # Allows numeric characters '0' thru '9'. % Allows numeric characters '0' thru '9' and ' '. 9 Allows numeric characters '0' thru '9', '.', '-', and '+'. ? Allows any character. * Allows any printable character. A Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '. D Allows date characters '0' thru '9', '-', and '/'. F Allows legal MS-DOS filename characters. H Allows hexadecimal characters '0' thru '9', 'A' thru 'F', and 'a' thru 'f'. L Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '. Input letters will be converted to lowercase. M Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '. Input letters will be converted to mixed case P Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '. Input letters will be displayed as spaces, which is useful for entering passwords. T Allows telephone number characters '0' thru '9', '(', ')', '-', and ' '. U Allows alpha characters 'A' thru 'Z', 'a' thru 'z', and ' '. Input letters will be converted to uppercase. W Allows legal MS-DOS filename characters, including wildcards. X Allows alphanumeric characters 'A' thru 'Z', 'a' thru 'z', '0' thru '9', and ' '. Y Allows yes/no response characters 'Y', 'N', 'y', and 'n'. (space) Space characters can be used throughout a format string to improve its readability. < Start of inclusion set. An inclusion set allows you to specify the only allowable characters for a position. > End of inclusion set. Any characters listed between the left and right angle brackets are part of the set. [ Start of exclusion set. An exclusion set allows you to specify characters that aren't allowed in that position. ] End of exclusion set. Any characters listed between the left and right square brackets are part of the set. ' Start or end of quoted text that will be displayed either in the input field or as you are typing. All characters in between the start and end quotes will be displayed as text. " Same as the single quote. Is useful if you need to actually display a single quote as text. Note that in C, you must represent the double quote inside the string as: \" 137 ! Start and stop a command toggle sequence. Any characters in between the start and stop exclamation points are treated as command toggles. You can have as many command toggles as you like between the exclamation points. Valid command toggles are listed below. Command Toggles are valid with inputsf() and winputsf() only! Command Toggle Description ------- ----------- - Decreases text attribute. Valid with winputsf() only. + Increases text attribute. Valid with winputsf() only. C Toggles copying of quoted characters to receiving buffer. The default is off. E Toggles Escape checking. When on, if Escape is pressed, the receiving buffer will be emptied and an error code will be returned. The default for inputsf() is on. The default for winputsf() is the value of the global variable _winfo.esc. L Toggles lower-case conversion. When on, all input letters will be forced to lower-case. The default is off. M Toggles mixed-case conversion. When on, input letters will be forced to upper-case for the first letter of each word and lower-case for the remaining letters. The default is off. P Toggles password mode. When on, input characters will be echoed to the screen as spaces. This is useful for password fields. The default is off. U Toggles upper-case conversion. When on, input letters will be forced to upper-case. The default is off. Examples: inputsf(name,"'Enter name: ' !UR! XXXXX !R! XXXXXXXXXX"); Prompts for name, inputs string from keyboard converting characters to uppercase as it goes, allows up to 15 alphanumeric characters as input. The return key is disabled until at least 5 characters have been entered. Input characters will be copied to the receiving buffer, name, which must be large enough to hold all 16 characters - 15 for the input string, and one for the terminating '\0'. winputsf(phone," 'Enter phone: '!RC! '(' ### ') ' ### '-' ####"); Prompts for a full phone number including area code, allows only digit characters and displays format punctuation as it goes. The entire field must be filled before return can be pressed. All of the characters except the prompt will be copied to the receiving buffer, phone. This buffer must be large enough to hold 15 characters - 10 for the phone number digits, 4 for the copied punctuation characters, and 1 for the terminating '\0'. winpdef( 1,16,date,"<01>#'/'<0123>#'/'<89>#",0,0,NULL,0); 138 Defines an input field that will accept a MMDDYY date. Note the use of the inclusion set '<' and '>' characters to aid in allowing only valid numbers. The receiving buffer, date, must be at least 7 characters to hold the 6 date characters and the terminating '\0'. 139 Appendix E - Input Field Editing Keys Key Action --- ------ LeftArrow cursor left RightArrow cursor right UpArrow cursor up DownArrow cursor down Ctrl-LeftArrow word left Ctrl-RightArrow word right Tab field right Shift-Tab field left Enter process field Ctrl-Enter process all fields Decimal (.) move to right side of decimal point Home beginning of field End end of field line / end of field Ctrl-Home beginning of first field Ctrl-End end of last field Ins toggle field insert mode Del delete character at cursor BackSpace delete character left Ctrl-BackSpace delete word left Ctrl-R restore field to original contents Ctrl-T delete word right Ctrl-U delete to end of field Ctrl-Y delete to end of last field Esc abort data entry (if Escape checking is on) 140